@medicus.ai/medicus-report-pdf-generator 1.3.13 → 1.3.15

package/docs/01-architecture-overview.md

@@ -0,0 +1,149 @@
+# 1. Architecture Overview
+
+## 1.1 What this package does
+
+`@medicus.ai/medicus-report-pdf-generator` (`package.json:2`) converts JSON health-report data into PDF documents for several distinct products:
+
+- **Core "Medicus" lab report** (biomarkers/panels/insights) — module `lib/pdf_generator.min.js`, called via `generateMedicusPDF`
+- **Wellbeing report** (questionnaire scores, PHQ‑9/GAD‑7 style) + optional merged lab "SmartReport" — module `lib/wellbeing_report_generator.js`, called via `generateNascoPDF` and `generateFullPdf`
+- **Corporate/aggregate analytics report** (population-level, for employers) — module `lib/corporate_report_generator.js`, called via `generateCorporateReportPDF`
+- **SanusX consumer wellbeing report** ("Health Hero" avatar report) — module `lib/sanusx_report_generator.js`, called via `generateSanuxPDF`
+
+All four are independent implementations. They do **not** share a common rendering module — each has its own copy of the "read HTML fragment from disk → string-replace `{{tokens}}` → load into jsdom → manipulate with jQuery → serialize → hand to Puppeteer" pattern. See [03-templating-and-rendering.md](03-templating-and-rendering.md).
+
+## 1.2 Directory map
+
+```
+index.js                    Public API — the only file a host app requires
+run.js                       Optional child-process wrapper around generateMedicusPDF
+lib/
+  pdf_generator.js            Core report renderer — SOURCE, but NOT what actually runs (see 1.4)
+  pdf_generator.min.js        Core report renderer — the file index.js actually requires
+  wellbeing_report_generator.js  Wellbeing + SmartReport renderer, plus PDF conversion for it
+  big_integral_questionnaire.js  Renders one static "Big Integral Questionnaire" table (Maison Sante only)
+  corporate_report_generator.js  Corporate/analytics report renderer
+  sanusx_report_generator.js     SanusX report renderer
+  template.js                  Shared rendering helpers used ONLY by wellbeing_report_generator.js
+                                (biomarker/panel/insight HTML builders, V3-suffixed functions)
+  sendEmail.js                 Nodemailer wrapper, used by the wellbeing/corporate/sanusx flows
+app/
+  i18n.config.js               i18n config for the core "Medicus" report (locales/)
+  i18n_wellbeing.config.js     i18n config for wellbeing/corporate/sanusx (locales/wellbeing/)
+  services/localeService.js    Thin wrapper exposing .t(key) / .setLocale(lang)
+config/                       One JSON per brand (whitelabelling) + default.json
+templates/                    HTML fragments — shared (templates/blocks) + per-brand folders
+locales/                      Translation JSON — main + locales/wellbeing subfolder
+assets/                       CSS/JS/fonts/images served into the rendered HTML, some per-brand
+output/                       Default write location for generated PDFs/HTML/logs (not cleaned up)
+testing-reports/              Example payloads used by test.js / preview scripts
+tests/                        Ad hoc test scripts (not a real test runner/framework)
+```
+
+## 1.3 Entry points (`index.js`)
+
+`index.js` exports a flat object of async functions. There is no class, no server, no routing — just functions a host app calls directly.
+
+- **`generateHTMLStaging`** — pipeline: Core. Build HTML only (re-exported straight from `pdf_generator.min.js`).
+- **`generateMedicusPDF(base64Object, isDebugging, isDownloadable, onlyHTML)`** — pipeline: Core. Full core lab report → PDF.
+- **`generateNascoPDF(data, isDebugging, isDownloadable, shouldSendEmail)`** — pipeline: Wellbeing. Plain wellbeing report, optionally emailed.
+- **`generateFullPdf(data, isDebugging, isDownloadable, shouldSendEmail, selectedLabs, showHeaderLogo)`** — pipeline: Wellbeing (extended). Branded wellbeing report + merged SmartReport + **encryption**.
+- **`generateSanuxPDF(data, isDebugging, isDownloadable, shouldSendEmail)`** — pipeline: SanusX. SanusX consumer report, optionally emailed.
+- **`generateCorporateReportPDF(json, isDebugging, isDownloadable)`** — pipeline: Corporate. Corporate/analytics report.
+- **`sendEmail(json)`** — fire a generic notification email (no PDF pipeline).
+- **`generateQrCode(json)`** — pipeline: Core (`generatePatientQR`). Rasterizes a caller-supplied HTML string (e.g. an inline SVG QR code) to PDF — despite the name, does not generate a QR code itself.
+
+**Payload convention:** every PDF-producing function expects the "real" data wrapped one level up: the caller passes a JSON *string* whose parsed object has a `data` field containing **base64-encoded JSON** (the actual report content), plus sibling fields like `client`, `language`, `host`/`port`/`authUser`/`authPass`/`sendFromEmail`/`secure` (SMTP config, only used if emailing) and, for `generateFullPdf`, `pdfPassword`. `generateMedicusPDF` is the odd one out — it takes the base64 payload directly as its first argument rather than nested inside a JSON envelope.
+
+```js
+// Illustrative shape of the outer envelope for generateNascoPDF / generateFullPdf / generateSanuxPDF
+{
+  "data": "<base64-encoded JSON string — the actual report payload>",
+  "client": "Mediclinic",      // whitelabel selector, see doc 2
+  "language": "en",            // or "ar", "ar-AE", "de", ...
+  "host": "smtp.example.com",  // only read if shouldSendEmail is true
+  "port": 587,
+  "authUser": "...",
+  "authPass": "...",
+  "sendFromEmail": "noreply@...",
+  "secure": true,               // NOTE: currently ignored, see doc 7
+  "pdfPassword": "..."          // generateFullPdf only — PDF is encrypted with this
+}
+```
+
+Every function decodes with `Buffer.from(base64Object, 'base64').toString('utf8')` then `JSON.parse` — this is **encoding, not encryption**; the payload (including any SMTP credentials riding alongside it) is trivially recoverable by anyone who can see the request. See [07-email-notifications.md](07-email-notifications.md) for the security implication.
+
+`run.js` is a thin optional wrapper that runs `generateMedicusPDF` in a forked child process (`process.on('message', ...)` / `process.send(...)`), for host apps that want report generation isolated from their main event loop. It is not required — most callers use `index.js` directly.
+
+## 1.4 Critical fact: the core report renderer that actually runs is `pdf_generator.min.js`, not `pdf_generator.js`
+
+`index.js:1` requires `./lib/pdf_generator.min` — **not** `./lib/pdf_generator`. These are commonly assumed to be a source-file/build-artifact pair (the kind that a bundler regenerates), but they are not:
+
+- There is **no build script** anywhere in the repo that produces `pdf_generator.min.js` from `pdf_generator.js` (no `webpack.config.js` exists, despite `webpack` being a devDependency).
+- Git history shows the two files are edited **completely independently**: `lib/pdf_generator.js` was last touched by commit `f31298e` ("fix range") on **2021-03-25**. `lib/pdf_generator.min.js` was last touched by commit `8bb73da` ("Reformat Code") on **2025-07-30** — over four years later — and that commit only reformatted/beautified the minified file (it went from a single packed line to ~525 readable lines); it did not re-minify from `pdf_generator.js`, which was untouched.
+- Today the two files happen to be logically equivalent in most places (verified by spot comparison), but this is coincidental, not enforced by any tooling. **A change made only to `lib/pdf_generator.js` will never ship** — `index.js` never loads it.
+
+**Practical rule: when working on the core "Medicus" lab-report pipeline, edit `lib/pdf_generator.min.js`.** Treat `lib/pdf_generator.js` as a legacy reference copy at best, and flag it for removal or for wiring up an actual build step. All other generators (`wellbeing_report_generator.js`, `corporate_report_generator.js`, `sanusx_report_generator.js`) do not have this problem — each is required directly from its single, non-minified source file.
+
+## 1.5 Data flow, at a glance
+
+```
+Host app                     This package                              Output
+─────────                    ────────────                              ──────
+JSON payload  ──base64──▶   index.js export
+                                │
+                                ▼
+                         decode base64 → JSON.parse
+                                │
+                                ▼
+                     generateHTML*(data, isDebugging, client, language)
+                       - loads config/{client}.json (branding)         ┐
+                       - loads templates/{brand or shared}/*.html       │ see doc 2 & 3
+                       - loads locales/{...}/{language}.json            │
+                       - fs.readFileSync HTML fragments,                │
+                         string .replace("{{token}}", value)            │
+                       - loads shell HTML into jsdom + jQuery            │
+                       - DOM-injects rendered fragments                 ┘
+                                │
+                                ▼  (HTML string, plus metadata: header/footer HTML, output file path)
+                     generatePDF*(html) — Puppeteer
+                       - page.setContent / page.goto(file://...)
+                       - page.pdf({ headerTemplate, footerTemplate, margin, ... })
+                       - (core report only) two page.pdf() calls merged via hummus,
+                         to give page 1 a different header than the rest
+                                │
+                                ▼  PDF Buffer
+                (generateFullPdf only) node-qpdf2 encrypts the buffer with reportData.pdfPassword
+                                │
+                                ▼
+                 return Buffer (isDownloadable) | base64 string | sendNascoEmail(...) result
+```
+
+## 1.6 Key third-party dependencies and why they're there
+
+- **`puppeteer`** (pinned `^1.15.0`, very old) — headless Chrome → PDF rendering, in all four generators. Each generator launches its own Puppeteer instance independently — no shared "renderPdf" helper.
+- **`hummus`** (`1.0.111`) — merging two separately-rendered PDF buffers (core report only, to give page 1 a distinct header). Effectively unmaintained upstream.
+- **`node-qpdf2`** — encrypting the final PDF with a password (`generateFullPdf` only). Dynamically `import()`-ed (ESM) inside a CommonJS file.
+- **`jsdom` + `jquery`** — server-side DOM construction and manipulation before handing HTML to Puppeteer. Used by every generator except the newer `template.js` V3 functions, which build HTML via plain string concatenation instead.
+- **`i18n`** (`^0.8.3`, resolves to `0.8.6`) — translation string lookup. Two independently configured instances — see doc 6.
+- **`nodemailer`** — sending report emails with the PDF attached. Transport config comes entirely from the caller's payload, not env vars.
+- **`chart.js`** (npm) — declared but **not actually used server-side** — dead import in `pdf_generator.js`. The real chart rendering uses a separately bundled copy, `assets/charts.min.js`, executed **inside the headless Chrome page** before the PDF snapshot is taken. Two independent copies of Chart.js that can drift out of sync.
+- **`qr-image` / `qrcode`** (npm) — also effectively unused server-side for the in-report PIN/QR box — that box is rendered client-side via the bundled `assets/qrcode.min.js`. `generatePatientQR` in `index.js`/`pdf_generator.min.js` is a generic "rasterize this HTML string" utility, not a QR generator itself.
+- **`canvas`, `get-canvas-context`, `self-adapt-fontsize`, `textfit`, `big-text.js`** — legacy font-fitting/canvas helpers. Present in `package.json` but not central to the current rendering path — treat as legacy.
+
+## 1.7 File/temp-file handling — an evolving pattern worth knowing
+
+Older code paths (`generateMedicusPDF`, `generateNascoPDF`, `generateSanuxPDF`, the internals of `pdf_generator.js`/`.min.js`) write intermediate HTML and the final PDF to **fixed, shared filenames** inside the package's own `output/` directory (e.g. `output/sample.pdf`, `output/nasco-sample.pdf`, `output/LOGS.txt`) and never delete them. Two concurrent requests through the same process can clobber each other's files.
+
+`generateFullPdf` (`index.js:194-314`) is the one flow that was hardened against this: it generates a `crypto.randomUUID()` per call and builds all temp paths (`wb-{callId}-in.pdf`, `wb-{callId}-enc.pdf`, `wb-{callId}-mail.pdf`) inside `os.tmpdir()`, then cleans them up in a `finally` block via a best-effort `safeUnlink`. **If you add a new PDF-producing flow, follow this newer pattern, not the older fixed-filename one.**
+
+## 1.8 Appendix: other root-level files (accounted for, not part of the runtime pipeline)
+
+A handful of files at the repo root are not required by `index.js` and are not wired into any of the four report pipelines. Listed here so nothing is silently unexplained:
+
+- **`test.js`**, **`tests/test.js`**, **`tests/test-qr-code.js`**, **`preview-big-integral.js`** — ad hoc developer scripts, not a test framework. See [`HANDOVER.md` §9](../HANDOVER.md#9-runningtesting-this-locally) for how to use them.
+- **`downloadfile.js`** — a one-off helper that fetches a pinned Chromium build for Puppeteer on Windows. Not required if Puppeteer's own Chromium download already succeeded during `npm install`.
+- **`data converter.js`** (53 lines) — a standalone script that parses an ad hoc "Antimicrobial Agent / Sensitivity" text format into structured rows. Not `require`d by anything in `lib/`, `index.js`, or `run.js` — an orphaned, one-off data-conversion utility from some prior integration, not part of the active rendering pipeline.
+- **`base64/cairo-font.js`** — a 2-line file containing a single, large base64-encoded font data URI. Not `require`d anywhere — orphaned/unused; the fonts actually used at render time are the files under `assets/fonts/`.
+- **`example.txt`** — a large (1000+ line) saved fragment of previously-rendered report HTML, kept as a manual reference/comparison sample, not consumed by any code.
+
+None of these affect report output; they're safe to leave alone or clean up opportunistically.

package/docs/02-configuration-and-whitelabelling.md

@@ -0,0 +1,111 @@
+# 2. Configuration & Whitelabelling
+
+Whitelabelling ("which brand does this report look like") is driven entirely by a **runtime string** — a `client` (or, for the corporate report, `clientName`) field in the request payload. There is no environment variable, no CLI flag, and no central "client registry" module. Each generator independently maps that string to a config JSON file and a template folder, and — this is the single most important thing to understand about this system — **the four generators do it four slightly different, inconsistent ways.**
+
+## 2.1 The `config/` directory
+
+One JSON file per brand, named after the client string, plus `config/default.json` as the fallback:
+
+```
+config/
+  default.json
+  Mediclinic.json
+  Pha.json
+  Najeeb.ai.json
+  bionext.json
+  diagnostikare.json
+  maisonsante.json
+  nasco.json          (referenced by filename convention; see 2.2 for how "nasco" resolves)
+  sanitas.json
+  sanusx.json
+```
+
+### Common schema (present in most/all files)
+
+- **`logo`** — Logo image, URL or base64 data-URI
+- **`body_icon`, `lifestyle_icon`, `mind_icon`, `bulb_icon`** — Section icons, URL or base64 data-URI
+- **`first-level-color` … `fifth-level-color`** — 5-step color ramp used for score/chart coloring
+- **`general-font-color`, `disclaimer-text-color`, `top-box-background`, `footer-background`** — Theme colors
+- **`body_font_color`, `list_icons_font_color`, `insights_font_color`** — More theme colors
+- **`signature`** — Free text signed off in emails/footers, e.g. `"Team Medicus"`, `"Team Sanitas"`
+- **`corporate_report`** — Nested object, see 2.1.1
+
+### Brand-specific keys
+
+- `title` — only `Mediclinic.json`, `Pha.json`, `maisonsante.json` (`"HealthRiskAssessment"`).
+- `score-header-color`, `score-description-color`, `svg-icon-color`, `low-score-text-color`, `section-title-border-color`, `first-section-scores-border-color`, `footer-border-color` — only `Mediclinic.json`, `Pha.json`, `maisonsante.json`.
+- `labs-logo` / `labs-logo-aliases` — **only `Pha.json`**. `labs-logo` maps a canonical lab key (e.g. `"labcorp"`, `"wp"`) to a base64 logo image. `labs-logo-aliases` maps the same keys to arrays of alternate spellings (e.g. `["lab corp", "lab_corp", ...]`) used to match whatever spelling the caller sends in `selectedLabs` (see doc 4, wellbeing SmartReport header logos).
+- `big_integral_questionnaire` — only `Pha.json` and `maisonsante.json`: `{ title, showHormonalFemale, showHormonalMale, colors: { headerBg, subheaderBg, headerText, rowBorder, elevatedText } }`. Consumed by `lib/big_integral_questionnaire.js` (see doc 5 — this module currently renders 100% mock data).
+
+#### 2.1.1 The nested `corporate_report` object
+
+```json
+"corporate_report": {
+  "logo": "...",
+  "main_color": "rgb(0, 0, 153)",
+  "report_date_color": "rgb(139, 139, 167)",
+  "section_title_color": "rgb(0, 0, 153)",
+  "section_title_border_color": "rgb(0, 158, 226)",
+  "chart_title": "rgb(139, 139, 167)",
+  "summary_background": "#e5f5fc",
+  "relation_content_border_color": "rgba(0, 0, 153, 0.3)",
+  "relation_content_bg": "#f2f2ff",
+  "table_tr_even_bg": "rgb(237, 237, 248)",
+  "recommends_bg": "rgba(0, 0, 153, 0.05)",
+  "recommends_title": "Moxie",
+  "show_medicus_logo": true,
+  "show_second_footer_logo": true
+}
+```
+
+`show_second_footer_logo` is missing from `sanusx.json` and `diagnostikare.json`. `bionext.json`'s `corporate_report` block additionally has its own `body_font_color`, unique to that one file.
+
+`Najeeb.ai.json` is essentially a duplicate of `default.json` (same colors, `signature: "Team Medicus"`) — a placeholder brand with no real customization yet. `sanitas.json` overrides `signature` ("Team Sanitas"), the color ramp, and `corporate_report.recommends_title` ("Sanitas") but otherwise mirrors the default.
+
+## 2.2 How `client`/`clientName` resolves to a config file — and why it's inconsistent
+
+There is no shared config-loader. Each generator reimplements the lookup:
+
+- **`wellbeing_report_generator.js`** (`loadClientConfig`) — Resolution logic: `'pha'` (any case) → `'Pha'`; otherwise uses the string as-is to build `config/{name}.json`; falls back to `config/default.json` via `fs.existsSync`. *Gotcha:* only `pha` gets special-cased; every other brand must be passed with exact on-disk casing.
+- **`corporate_report_generator.js`** — Resolution logic: `client = data.clientName.toLowerCase()`, then `config/{client}.json`. *Gotcha:* **lower-cases before lookup**, but the actual files are capitalized (`Mediclinic.json`, `Pha.json`, `Najeeb.ai.json`). This only works on case-insensitive filesystems (Windows/macOS default). On a case-sensitive Linux filesystem, `clientName: "Mediclinic"` silently falls back to `default.json`.
+- **`lib/sendEmail.js`** (`sendNascoEmail`) — Resolution logic: uses the **raw, unmodified** client string, no lower-casing, no `pha`→`Pha` mapping. *Gotcha:* caller must pass the exact on-disk filename casing, a different rule than the wellbeing generator it's normally called alongside.
+- **`sanusx_report_generator.js`** — Resolution logic: **ignores `clientName` for config entirely** — unconditionally `require('../config/sanusx.json')`. *Gotcha:* the `client` parameter this generator accepts is only used later to add a CSS class (`$(".score-main").addClass(client)`), which currently matches no CSS rule — effectively a no-op. SanusX is single-brand in practice.
+- **`lib/pdf_generator.js` / `.min.js`** (core report) — Resolution logic: does not touch `config/` at all. *Gotcha:* branding for the core report must arrive pre-baked inside the data payload from the host app — there is no per-client config file in this pipeline.
+
+**Practical consequence:** if you're onboarding a new brand, check *which* generator you're using before assuming "just add `config/NewBrand.json`" is enough — confirm the exact casing rule for that specific generator, and remember `sanusx_report_generator.js` won't pick it up at all without a code change.
+
+One more special case: `wellbeing_report_generator.js:1341-1353` hard-codes a feature gate — when `client.toLowerCase() === 'maisonsante' && data.IsDoctor`, it re-reads `config/maisonsante.json` a second time (bypassing the already-resolved config object) specifically to feed `big_integral_questionnaire.js`.
+
+## 2.3 Config → colors/branding, not template choice, in most flows
+
+Loading `config/{client}.json` gives you colors/logos/icons that get injected as inline `<style>` overrides or `{{token}}` substitutions into whatever HTML template was already chosen (see 2.4) — it does **not**, by itself, choose which template folder is used. Two exceptions: the corporate report and SanusX generators always use one fixed template folder regardless of config; only the wellbeing "extended" (SmartReport) flow ties template folder selection directly to the client string.
+
+## 2.4 Template folder selection — no blocks-level fallback
+
+`templates/` has full per-brand subfolders for **`Mediclinic`**, **`Pha`**, and **`maisonsante`** (each with `ltr_no_pages.html`, `rtl_no_pages.html`, `wellbeing_template.html` and its own `blocks/`), a generic **`wellbeing`** folder used as the default, a **`sanusx`** folder, plus non-brand folders `corporate_report/`, `imc/`, `popup/`, and the shared top-level `templates/blocks/`.
+
+- **Core report** (`pdf_generator.min.js`) — always `templates/blocks/*` (+ `templates/imc/first-header-template.html` for one specific lab type). No per-brand folder is ever consulted; all differentiation happens through the data payload, not through swapped templates.
+- **Wellbeing, plain** (`generateHTMLWellbeingReport` → `loadWellbeingTemplates`) — always `templates/wellbeing/` regardless of client. Brands going through this flow are differentiated purely by injected config colors/logo.
+- **Wellbeing, extended/SmartReport** (`generateHTMLWellbeingReportWithSmartReport` → `loadExtendedTemplates`) — derives the folder name **directly from the client string** (`'pha'→'Pha'`, `'mediclinic'→'Mediclinic'`, else used as-is) → `templates/{ClientName}/`. Reads every block with `fs.readFileSync` and **no existence check** — if the folder or a block inside it is missing, it throws `ENOENT`. Only works today for clients with a dedicated folder: `Mediclinic`, `Pha`, `maisonsante`.
+- **Corporate report** — always `templates/corporate_report/*`, regardless of client.
+- **SanusX** — always `templates/sanusx/*`, regardless of client.
+
+There is **no fallback from a brand folder to the shared `templates/blocks/`** for an individual missing block — brand folders are complete, parallel copies, not overrides layered on a shared base. If you add a fourth brand to the "extended" wellbeing flow, you must create a full `templates/{Brand}/` folder with every block file the existing three have, or the render will crash.
+
+## 2.5 Brand asset directories
+
+`assets/Mediclinic/`, `assets/pha/labcrop-logo.png`, `assets/sanusx/`, `assets/imc/`, `assets/corporate_report/`, `assets/wellbeing/`, `assets/medicus_pdf/*.css`.
+
+Notable: **`templates/Pha/*.html` and `templates/maisonsante/*.html` both reference `../assets/Mediclinic/css/...` and `../assets/Mediclinic/js/js.js`** — Pha and Maison Sante do not have their own CSS/JS bundle; they reuse the Mediclinic bundle wholesale and rely entirely on the `config/{Client}.json` color values for visual differentiation. `templates/corporate_report/cover_page.html` also hard-codes a Nasco logo image path regardless of client, unless overridden by config.
+
+## 2.6 Environment variables
+
+There is exactly **one** environment variable read anywhere in the codebase: `SHOW_QR_BOX` (`lib/template.js`), which toggles whether the in-report PIN/QR box renders. It has nothing to do with whitelabelling. **No environment variable selects a client, config, or template.**
+
+## 2.7 Step-by-step trace: "given `client = X`, what actually loads?"
+
+1. Host app calls an `index.js` export with `client: X` (or `clientName: X` for the corporate report) inside the payload.
+2. The generator resolves `X` to `config/{mapped X}.json` if it exists, else `config/default.json` — using whichever mapping rule from §2.2 applies to that generator.
+3. Config values (colors, logo, icons, `corporate_report`/`big_integral_questionnaire` sub-objects) get inlined into the HTML as `<style>` overrides / `{{token}}` substitutions.
+4. The template folder is chosen per §2.4 — for three of the four generators this is *independent* of `X`; only the "extended" wellbeing flow ties folder choice to `X`.
+5. Assets are pulled in via relative `<link>`/`<script>` tags baked into whichever template was chosen — mostly `assets/Mediclinic`, `assets/wellbeing`, `assets/sanusx`, `assets/corporate_report`, or `assets/imc` — independent of `X` except for the config-driven inline color overrides.

package/docs/03-templating-and-rendering.md

@@ -0,0 +1,71 @@
+# 3. Templating & Rendering Pipeline
+
+## 3.1 There is no template engine
+
+Despite the `templates/` folder full of `.html` files, this project does **not** use Handlebars, EJS, Mustache, or any templating library. Every generator (core, wellbeing, corporate, sanusx) hand-rolls the same two techniques:
+
+**(a) Plain string `{{token}}` replacement**, for fragments Puppeteer needs as raw strings (Chrome's `headerTemplate`/`footerTemplate` print options only accept static HTML strings, so these can't be manipulated after the fact):
+```js
+headerTemplate = headerTemplate
+    .replace("{{logo}}", img)
+    .replace("{{patient_name}}", patientName)
+    .replace("{{report_ref}}", fitNumber(data.reportNumber))
+    // ...
+```
+
+Block files contain literal `{{...}}` tokens, e.g. `templates/blocks/header.html` (`{{patient_name}}`, `{{report_ref}}`, `{{division_name}}`, `{{report_date}}`), `templates/blocks/doctor-note.html` (`{{note-id}}`), `templates/blocks/panel-details.html` (`{{panel-id}}`, `{{panel-title}}`).
+
+Note: `lib/sendEmail.js` uses a **different** placeholder convention for its own hand-built HTML — single-brace `{token}` (e.g. `{logo}`, `{header_text}`) — not `{{double-brace}}`. If you're hunting for a placeholder and it's an email string, look for single braces.
+
+**(b) jQuery-over-jsdom DOM manipulation**, for the main body of each report. The pattern:
+
+1. Load a page-skeleton HTML file (e.g. `templates/ltr_no_pages.html`) with `fs.readFileSync`.
+2. `let dom = new JSDOM(html); $ = require('jquery')(dom.window);` — construct a real DOM in Node and bind jQuery to it.
+3. Load each block fragment, do its `{{token}}` replacements, then inject it into the DOM by selector: `$('#content').append(newPanelHtml)`, `$("#reference").text(data.reportNumber)`, `$('.patient-table').html(...)`, `$(selector).remove()`, etc.
+4. Serialize the whole document back to a string with `dom.serialize()` and write it to a temp/output HTML file.
+5. Puppeteer loads that file via a `file://` URL and rasterizes it to PDF (see 3.3).
+
+This exact five-step pattern is duplicated **independently** in `lib/pdf_generator.min.js`, `lib/wellbeing_report_generator.js`, `lib/corporate_report_generator.js`, and `lib/sanusx_report_generator.js` — there is no shared "render engine" module between them, only convention.
+
+`lib/template.js` is a partial exception: it contains a newer, parallel set of rendering functions (suffixed `V3` — `renderBiomarkerV3`, `renderPanelV3`, `renderNoteV3`, etc.) that build HTML purely via JS template-literal string concatenation, with no `fs.readFileSync` of block `.html` files and no jsdom/jQuery for those specific pieces. `template.js` is used **only** by `wellbeing_report_generator.js` (for rendering the merged "SmartReport" biomarker section) — it is not shared with the core report's own (older, still jsdom/jQuery-based) biomarker rendering in `pdf_generator.min.js`, even though the two do very similar things. This suggests the codebase is mid-migration from "external HTML blocks + jQuery/jsdom" toward "HTML generated inline in JS," but the migration has only reached the wellbeing pipeline so far.
+
+## 3.2 Top-level page templates — live vs. dead
+
+Only two root-level templates are actually loaded at runtime by the core report: **`templates/ltr_no_pages.html`** and **`templates/rtl_no_pages.html`**, chosen by a single `isRtl` boolean. Both are minimal skeletons — a `<head>` pulling in `charts.min.js`/`qrcode.min.js`, empty containers (`#patient-container`, `#more-link`, `#pin`, `<canvas id="canvas">`), and one empty `<div id="content">` that everything else gets appended into. The RTL variant additionally sets `dir="rtl" lang="ar"` and loads `arabic.min.css`/`translation.min.js`. Neither contains manual page-break markup — pagination is left entirely to the print engine, which is why they're named `*_no_pages` (as opposed to the older, page-per-`<div class="paper">` style below).
+
+`templates/imc/first-header-template.html` is swapped in only for one specific lab type (`labType === 9`, a wide custom header).
+
+The remaining root-level files — `templates/base.html`, `templates/template.html`, `templates/ltr.html`, `templates/no_pages.html`, `templates/empty.html`, `templates/first_page_head.html` — are **not referenced by any code path** (confirmed by grep across all of `lib/`). They are static mockups/prototypes from earlier iterations of the pagination model (manual `<div class="paper">` per-page blocks with repeated headers/footers) or trivial smoke-test fixtures. Don't assume editing them affects output — they're dead weight, safe candidates for removal but currently harmless if left alone.
+
+## 3.3 PDF conversion (Puppeteer)
+
+Each generator launches its own Puppeteer instance and calls `page.pdf(...)` with its own options — there is no shared "renderPdf" helper across the four pipelines.
+
+**Core report** (`pdf_generator.min.js`) calls `page.pdf()` **twice**, because Chrome's print header/footer can't vary within a single call:
+- Once for `pageRanges: '1'` with the "first page" header template and different top margin (page 1 needs the patient-info/QR header).
+- Once for `pageRanges: '2-'` with the regular header template.
+
+The two resulting PDF buffers are then merged into one file using `hummus` (`createWriterToModify(...).appendPDFPagesFromPDF(...)`).
+
+**Wellbeing / Corporate / SanusX** each call `page.pdf()` once, with their own `headerTemplate`/`footerTemplate`/margins tuned per report type. The SanusX generator additionally passes `pageRanges: '1'`, meaning **any content overflowing page 1 is silently dropped** — a fragile single-page assumption worth remembering if SanusX report content ever grows (e.g. longer translated strings pushing content past one page).
+
+The corporate report generator sets page content **twice** — once via `page.setContent(...)` and again by navigating to the serialized temp HTML file via `page.goto("file://...")` — and separately injects jQuery from a public CDN (`cdn.jsdelivr.net`) mid-render via `page.addScriptTag`. This means corporate-report rendering has a live external-network dependency at PDF-generation time, unlike the other three pipelines which bundle their own JS/CSS as local `assets/` files.
+
+## 3.4 Charts
+
+There is no server-side chart *image* generation. The npm `chart.js` package is `require`d at the top of `pdf_generator.js`/`.min.js` but never actually called — a dead import. Instead:
+
+1. Server-side, biomarker history is serialized into a plain JS array (`{id, dataset, dataColor, dataLabel}` per biomarker) and injected into a `<script>` tag as `var chartsData = [...]`.
+2. The page template loads a **separately bundled, minified browser copy of Chart.js 2.x** — `assets/charts.min.js` (not the npm package).
+3. `assets/js.js`'s `drowBioCharts()` function runs **inside the headless Chrome page itself**, before `page.pdf()` is called, and instantiates real `Chart(ctx, {type:'line', ...})` objects against `<canvas>` elements.
+
+So charts are rendered client-side, in-browser, immediately before the PDF snapshot — a legitimate technique, but it means the npm `chart.js` dependency and `assets/charts.min.js` are two independent copies of the same library that can silently drift out of version sync.
+
+The corporate report's bar charts don't use a charting library at all: `renderBarChart()` emits plain `<div class="bar-chart" data-value=".." data-total="..">` elements, and `assets/corporate_report/js/js.js` computes their pixel width client-side via `$(this).css("width", "calc(" + percent + "% + 60px)")`. SanusX's score "gauges" are similarly library-free — static PNG segment-circle images overlaid with a CSS-rotated needle (`transform: rotateZ(...)`), not a canvas or SVG chart.
+
+## 3.5 QR codes — two unrelated mechanisms
+
+Don't confuse these:
+
+1. **The in-report patient PIN/QR box** (page 1 "more info" panel): the server builds a plain concatenated string (`'v_' + patientName + '_!_' + pin`, misleadingly assembled near variables named `base64text`/`base64name`/`base64pin` that are computed but never actually used), injects it as a script variable, and `assets/js.js`'s `drawQRCode()` calls `QRCode.toCanvas(...)` **client-side, in-browser**, using the bundled `assets/qrcode.min.js`, targeting a `<canvas id="canvas">` in the page template.
+2. **`generatePatientQR(data)`** (exported from `index.js` as `generateQrCode`) — despite its name, this function does **not generate a QR code**. It takes an **already-fully-rendered HTML string** from the caller (e.g. containing an inline `<svg>` QR code the caller produced elsewhere), wraps it in jsdom, writes it to a temp file, and rasterizes it to a `letter`-format PDF with no margins/headers via Puppeteer. It is a generic "HTML string → PDF" utility that happens to be used for QR codes by convention, not a QR-code generator itself. See `tests/test-qr-code.js` for the expected caller-side pattern (pre-render the QR as inline SVG, then pass the whole HTML string in).

package/docs/04-report-pipelines.md

@@ -0,0 +1,128 @@
+# 4. Report Pipelines
+
+Four independent report types. Each has its own generator module, its own template folder(s), and its own quirks.
+
+---
+
+## 4.A Core "Medicus" Lab Report
+
+**Module:** `lib/pdf_generator.min.js` (the file that actually runs — see [doc 1.4](01-architecture-overview.md#14-critical-fact-the-core-report-renderer-that-actually-runs-is-pdf_generatorminjs-not-pdf_generatorjs)). `lib/pdf_generator.js` is a stale reference copy.
+
+**Purpose:** a clinical lab report — biomarkers grouped into panels, each with reference ranges, history charts, doctor notes, and AI/clinical "insights." No questionnaire concept at all.
+
+**Entry points:** `generateHTMLStaging(data, isDebugging)` → HTML; `generatePDF(html)` → PDF buffer via Puppeteer; both wired together by `index.js`'s `generateMedicusPDF`. `generatePatientQR(data)` is a separate, generically-named "HTML string → PDF" utility (see [doc 3.5](03-templating-and-rendering.md#35-qr-codes--two-unrelated-mechanisms)).
+
+**Data shape (top-level fields observed in the code and `assets/data/data2.json`):**
+```
+language, labType (9 = "IMC lab", triggers customHeader), labLogo, labName, labAddress,
+labPhoneNumber, patientName, patientPin, showPIN, timeZoneOffset, reportDate (unix seconds),
+reportNumber, reportDivision, reportTitle, copyright, moreLink, showCompactView, showDetailsView,
+profileItems: [{title, value}],
+panels: [{ panelId, name, panelDetails, notes,
+           biomarkers: [{ id, name, fullName, unit, value, formattedValue, color, isNormal,
+                          showInCompactView, showInDetailsView, ranges[], history[],
+                          childrenBiomarkers[], doctorNotes[], relatedInsights[],
+                          status, insightsCount }],
+           insights: [...] }],
+summary: [{ ...stat insights, stackedInsight, relatedBiomarkers, isClinicalReading }],
+doctorNote: [{ id, createdByName, content }],
+reportSummary, reportProperties,
+signatures: [{ name, signatureURL }], labStamp, approvalDate
+```
+
+**Templates:** always `templates/blocks/*.html` (shared, non-brand) plus `templates/imc/first-header-template.html` for `labType === 9`. No per-brand template folder is ever consulted in this pipeline — whitelabelling here happens entirely through data values the host app bakes into the payload (logo URL, colors would need to be pre-applied since there's no `config/` lookup at all in this file).
+
+**Notable quirks:**
+- Module-level mutable state (`$`, `debug`, `OUT_FILE`, `Pdf_file`, `shouldRenderCustomHeader`) is reassigned per call with no isolation — concurrent calls in the same process can interfere with each other (contrast with `generateFullPdf`'s UUID-based temp files).
+- Every render leaves a timestamped HTML file behind in the package's own `output/` directory; nothing is cleaned up.
+- `labType === 9` ("IMC") special-casing runs throughout what's otherwise framed as the generic/core pipeline.
+- Pinned to very old `puppeteer@^1.15.0` and `hummus@1.0.111`.
+
+---
+
+## 4.B Wellbeing Report (+ optional merged "SmartReport")
+
+**Module:** `lib/wellbeing_report_generator.js` (2000+ lines), using shared rendering helpers from `lib/template.js` for the SmartReport section, and `lib/big_integral_questionnaire.js` for one Maison-Sante-only static table.
+
+**Purpose:** a patient-facing wellbeing/lifestyle report — physical/psychological/lifestyle scores, PHQ‑9/GAD‑7-style questionnaire answers (when a doctor reviewed it), and tips. Optionally merged with a full lab biomarker report ("SmartReport").
+
+There are **two distinct entry functions** with materially different behavior:
+
+**`generateHTMLWellbeingReport`** (the plain flow):
+- Signature: `(data, isDebugging, clientName, language)`
+- Template folder: always `templates/wellbeing/` (generic), regardless of client
+- Data source: top-level `data.calculation` / `data.partsScore` / `data.insights.tips`
+- Called from: `generateNascoPDF` (`index.js`)
+- PDF conversion: `generatePDFWellbeingReport(html)`
+
+**`generateHTMLWellbeingReportWithSmartReport`** (the branded/extended flow):
+- Signature: `(data, isDebugging, clientName, language, selectedLabs=[], showHeaderLogo=true, hideWellbeingUI=false)`
+- Template folder: `templates/{Mediclinic, Pha, or maisonsante}/` — client-specific, throws if the client has no dedicated folder
+- Data source: `data.wellbeing` (scores), `data.profileInfo` (metadata), `data.Profile` + `data.IsDoctor` (Q&A), `data.SR` (merged SmartReport lab data)
+- Called from: `generateFullPdf` (`index.js`) — the only flow that also encrypts the output
+- PDF conversion: `generatePDFReport(data, hideWellbeingUI)` — adds running header/footer, `data.footer` support
+
+**Brand/theme support:** `loadColorTheme` explicitly supports **mediclinic, pha, nasco, maisonsante**. Any other client string (`bionext`, `diagnostikare`, `sanitas`, `sanusx`, `Najeeb.ai`) silently falls back to the mediclinic color theme.
+
+**SmartReport merge (`data.SR`):** a full lab/biomarker report payload (same general shape as the corporate report's item list: `items[]` of `biomarker`, `panel`, `insight`, `biomarkerNote`, `allergyItems`, etc.), parsed as string or object, run through `generateReportHtml()` (reusing `renderReportItems`/`renderSummary`/`renderHTMLTemplate` from `lib/template.js`), and injected into `#smart-report`. If `hideWellbeingUI` is true or `data.wellbeing` is empty, the quiz-UI sections are removed from the DOM so only the lab report shows.
+
+**`selectedLabs` / `showHeaderLogo`:** used to decide which lab logos appear in the header, normalized against `config.labs_logo`/`labs_logo_aliases` (Pha only — see [doc 2.1](02-configuration-and-whitelabelling.md#211-the-nested-corporate_report-object)) so different spellings of a lab name (`"lab corp"`, `"LabCorp"`) resolve to one config entry.
+
+**Known bug:** `index.js` passes `showHeaderLogo || true` into the generator. Since `false || true === true`, **the header logo can never actually be suppressed**, contradicting both the parameter name and its JSDoc in `index.js`.
+
+**Localization:** uses `app/i18n_wellbeing.config.js` / `locales/wellbeing/*.json` (not the main `locales/` set — see [doc 6](06-internationalization.md)).
+
+**Encryption:** only `generateFullPdf` in `index.js` encrypts the final buffer, using `node-qpdf2` with `reportData.pdfPassword`. `wellbeing_report_generator.js` itself has no encryption logic — it only ever returns a plaintext PDF buffer.
+
+**Other quirks worth knowing:**
+- Per-client special-casing is scattered as inline conditionals rather than being config-driven: PHA-only CSS overrides, PHA-only bottom margin, hardcoded per-client addresses/phone numbers in the footer builder, tips category ordering swapped for `pha`, header-logo sizing branched by client name. Onboarding a new client for this flow means hunting through many such `if (client === ...)` branches, not editing one config file.
+- `generateHeaderInfo()`'s output is computed but discarded — its target selector `.report-info` is commented out in all three brand `blocks/header.html` files. The live equivalent is `renderPatientTable()`, which injects into `.patient-table`.
+- `templates/{wellbeing,Mediclinic,Pha,maisonsante}/wellbeing_template.html` files are not referenced by any `.js` file — orphaned, superseded by `ltr_no_pages.html`/`rtl_no_pages.html`.
+- Shared mutable module state (`config`, the singleton `localeService`/`i18n`, a module-level `debug` flag) is reassigned per call; file paths were hardened against concurrent-request collisions (per an in-code comment referencing a real past bug) but config/locale/debug state was not similarly isolated — concurrent requests for different clients/languages can still race.
+
+### 4.B.1 `lib/big_integral_questionnaire.js` — read this before assuming it's a real feature
+
+This module is **not** a scoring engine and does **not** read real questionnaire answers from the input payload. It is a presentational renderer for one static demo table ("Key to the Big Integral Questionnaire" — a functional-medicine systems review, unrelated to the PHQ‑9/GAD‑7 wellbeing scores) built entirely from `getDummyData()`, which returns 11 hardcoded rows with `result: 0` for every row and a fixed fake patient (`"Final Test 3"`, age 37). The single export, `renderBigIntegralQuestionnaire({ clientConfig })`, merges `clientConfig.big_integral_questionnaire` colors/toggles (from `config/maisonsante.json`) and renders the table. It is invoked only when `client.toLowerCase() === 'maisonsante' && data.IsDoctor`, targeting `#big-integral-section` (present only in `templates/maisonsante/ltr_no_pages.html`). `preview-big-integral.js` is a standalone dev harness confirming this is a design/preview scaffold, not a wired, data-driven feature. **If a stakeholder asks "why doesn't the Big Integral Questionnaire reflect the patient's real answers" — that's not a bug, it was never wired to real data.**
+
+---
+
+## 4.C Corporate Report
+
+**Module:** `lib/corporate_report_generator.js`.
+
+**Purpose:** an aggregate/analytics PDF summarizing results across a *population* of participants (e.g. an employer's workforce), not a single patient — cover page, "Participant Analytics" section (per-metric bar charts), then one page per health "element" with a summary, bar charts, textual "relations," a gender-breakdown table, recommendations, and sources. Built for HR/benefits stakeholders.
+
+**Entry points:** `generateHTMLCorporateReport(data, isDebugging)` → HTML; `generatePDFCorporateReport(html)` → PDF; wired together by `index.js`'s `generateCorporateReportPDF(json, isDebugging, isDownloadable)`.
+
+**Data shape:** `data.clientName` (branding selector), `data.language`, `data.participantAnalytics: [...]` (drives the Participant Analytics bar charts — the `participant_analytics.html` template itself is just an empty `<div class="container">`; all its content is generated in JS), `data.elements: [{ summary, chartValues, secondChartValues, relations, dataByGender, recommends, sources }]`.
+
+**Templates:** always `templates/corporate_report/*` (`cover_page.html`, `participant_analytics.html`, `page.html`, `footer.html`), regardless of client — only colors/logo vary by `config/{client}.corporate_report`.
+
+**RTL:** this generator correctly branches to `templates/corporate_report/rtl_no_pages.html` vs `ltr_no_pages.html` based on `data.language` containing `"ar"` — unlike SanusX (4.D), RTL is not broken here.
+
+**Notable quirks:**
+- Sets page content twice (`page.setContent` then `page.goto(file://...)`) and injects jQuery from a public CDN mid-render (`page.addScriptTag({ url: 'https://cdn.jsdelivr.net/...' })`) — a live external-network dependency at render time.
+- Contains a copy-pasted, entirely dead `combinePDFBuffers` function (and the `hummus`/`memory-streams` requires that exist only to support it) — never actually invoked in this file.
+- Onboarding a new client's custom cover-page background image requires editing shared CSS by client-name string (`.cover-overlay-container.bionext { background-image: url(...) }` in `assets/corporate_report/css/report.css`) — bypasses the otherwise config-JSON-driven theming model.
+- Corporate-report translation strings live inside the `locales/wellbeing/` bucket (via `app/i18n_wellbeing.config.js`), not a dedicated namespace — a naming trap when hunting for a string to translate.
+
+---
+
+## 4.D SanusX Report
+
+**Module:** `lib/sanusx_report_generator.js`.
+
+**Purpose:** a branded, single-consumer wellbeing product ("Your Health Hero") — an individual is scored on physical/psychological axes and assigned an avatar archetype (monkey/tiger/owl) with a "superpower," a strength/weakness, three predicted-vs-actual insight cards, and three tips cards. The SanusX-brand analogue of the wellbeing report.
+
+**Entry points:** `generateHTMLSanusXReport(data, isDebugging, clientName, language)` → HTML; `generateSanusXReport(html)` → PDF; wired together by `index.js`'s `generateSanuxPDF`.
+
+**Data shape:** `data.highestAvatarScorePartId` (1/2/3, maps to monkey/tiger/owl), score fields feeding a rounded physical/psychological score bucketed into low/med/high (drives a static PNG "speedometer" image + CSS-rotated needle, not a real chart), `data.PartScoresHighestValues.{body,mind,lifeStyle}[0].isPredictiveElement` (drives "predicted right/wrong" copy), `data.insights.tips` (3 items, split into lifestyle/body/mind cards).
+
+**Templates:** always `templates/sanusx/*`, regardless of `clientName`.
+
+**Notable quirks — more fragile than the other three pipelines:**
+- **Ignores `clientName` for branding entirely.** Config is hardcoded to `require('../config/sanusx.json')`. The `client` parameter is only used to add a CSS class (`$(".score-main").addClass(client)`) that currently matches no rule in `assets/sanusx/css/sanusx_report.css` — a no-op.
+- **RTL is broken/incomplete.** There's a comment (`/*check if the language is an RTL language*/`) with no logic after it — `templates/sanusx/ltr_no_pages.html` is loaded unconditionally regardless of `language`. `templates/sanusx/rtl_no_pages.html` exists on disk but references asset paths from the *wellbeing* report (`assets/wellbeing/css/nasco_report.css`) that don't exist under `assets/sanusx/` — it is dead, unreachable code, not a working alternative.
+- **`page.pdf({ pageRanges: '1', ... })` hard-limits output to one page** — any overflow (e.g. from longer translated strings) is silently dropped rather than flowing to a second page.
+- `templates/sanusx/blocks/tips.html` exists on disk but is never read by this generator (dead file) — the actual tips rendering is done by an in-file `renderInsightTips()` function building HTML via string concatenation.
+- Reuses `sendNascoEmail` (named after a different client) for its email flow, same as the wellbeing and corporate pipelines — a shared helper with a client-specific name baked into shared infrastructure.

package/docs/05-questions-and-data-model.md

@@ -0,0 +1,67 @@
+# 5. Questions, Answers & the Data Model
+
+This section directly answers the question: **"How do we render a question, and where does the question text come from?"**
+
+## 5.1 The headline fact: there is no question bank in this codebase
+
+This package does not store, own, or look up questionnaire questions. There is no database, no question-ID → question-text mapping, no survey-definition file anywhere in the repository. **Every question's title text and its answer value arrive together, pre-rendered, as flat `{title, value}` pairs inside the JSON payload the host application sends in.** This package's job is purely to lay that text out on the page — not to know what the questions mean, score them, or validate them.
+
+This matters operationally: if a question's wording is wrong in a PDF, the fix is almost never in this repository — it's in whatever upstream system assembled the `Profile`/`profileInfo` array before base64-encoding it and calling this library.
+
+## 5.2 Where question/answer data lives, per pipeline
+
+### Core "Medicus" lab report — no questions at all
+
+This pipeline's domain model is biomarkers/panels/insights/doctor-notes/signatures (see [doc 4.A](04-report-pipelines.md#4a-core-medicus-lab-report)). Grepping the entire core renderer for "question" or "answer" returns nothing. If you need to document or debug question rendering, **you are in the wrong pipeline** — go to the wellbeing report instead.
+
+### Wellbeing report — `data.Profile` (the actual Q&A) and `data.profileInfo` (metadata)
+
+Two separate arrays, both flat `{title, value}` lists, both only meaningfully populated when `data.IsDoctor === true`:
+
+```js
+// testing-reports/mediclinic/doctor-data.js — a real fixture used by test.js
+{
+  "IsDoctor": true,
+  "Profile": [
+    { "title": "What is your gender?", "value": "Male" },
+    { "title": "When is your birthday?", "value": "51 years" },
+    { "title": "What is your height?", "value": "178 cm" },
+    { "title": "Do you have any of the following conditions?", "value": "Asthma" },
+    { "title": "Do you have a family history of any condition?",
+      "value": "Diabetes: No one | High blood pressure: No one" },
+    { "title": "Over the last 2 weeks, how often have you been bothered by feeling down, depressed, or hopeless?",
+      "value": "More than half the days" },
+    // ... a full PHQ-9 / GAD-7 style clinical questionnaire, plus lifestyle questions
+  ]
+}
+```
+
+- **`data.Profile`** — the real questionnaire content (PHQ‑9/GAD‑7-style clinical questions plus lifestyle questions). Rendered by `renderDoctorDetails(doctorData)` in `lib/wellbeing_report_generator.js`: each item becomes a two-column row — `.question-title` for `item.title`, `.details-value` for `item.value` — under a "Quiz Answers" header, injected into `.doctor-details` in the page DOM. **Neither the question title nor the answer value is HTML-escaped here** — see the security note in 5.4.
+- **`data.profileInfo`** — patient/report metadata (LAB, Reference, Patient name, Report date, Date of birth, Weight, Height, Gender, BMI, Blood Pressure, Waist Circumference), *not* questionnaire answers. Split by array index: the first 4 entries go through `generateHeaderInfo()` (whose output is actually **dead** — its target `.report-info` is commented out of every brand's `header.html`), the rest go through `renderPatientTable()`, which *does* escape the label (not the value) and is injected live into `.patient-table`.
+- Numeric wellbeing **scores** (as opposed to raw Q&A text) come from a different part of the payload — `data.wellbeing.calculation` / `data.wellbeing.partsScore` — pre-computed upstream; this package does not calculate PHQ‑9/GAD‑7 scores itself, it only displays whatever score value it's handed.
+
+### `lib/big_integral_questionnaire.js` — a cautionary example, not a real data source
+
+As covered in [doc 4.B.1](04-report-pipelines.md#4b1-libbig_integral_questionnairejs--read-this-before-assuming-its-a-real-feature), this module currently renders **100% hardcoded dummy data** (`getDummyData()` — 11 fixed rows, `result: 0` for all of them, a fake patient name). It is not wired to any real answer data in the payload today. Do not use it as a reference for "how question rendering should work" — use `renderDoctorDetails`/`data.Profile` instead.
+
+### Corporate report and SanusX — no free-text Q&A
+
+Neither of these two pipelines renders question/answer pairs in the `data.Profile` sense. The corporate report works with pre-aggregated `data.elements[]` (population-level summaries, chart values, gender breakdowns — see [doc 4.C](04-report-pipelines.md#4c-corporate-report)). SanusX works with pre-computed scores and flags (`highestAvatarScorePartId`, `isPredictiveElement` — see [doc 4.D](04-report-pipelines.md#4d-sanusx-report)). Both assume all interpretation/scoring already happened upstream.
+
+### "SmartReport" biomarker notes — a different kind of "note," not a question
+
+When a wellbeing report is merged with lab data (`data.SR`, see [doc 4.B](04-report-pipelines.md#4b-wellbeing-report--optional-merged-smartreport)), individual biomarkers can carry `doctorNote`/`biomarkerNote`/`insight` entries. These are clinician-authored free-text notes attached to a specific lab value — a different concept from a questionnaire answer — rendered via `renderReportItems`/`renderNoteV3` in `lib/template.js`, not via `renderDoctorDetails`.
+
+## 5.3 Summary
+
+- **`data.Profile`** (Wellbeing) — real questionnaire Q&A (title + value pairs). Rendered by `renderDoctorDetails` → `.doctor-details`. **Not** HTML-escaped.
+- **`data.profileInfo`** (Wellbeing) — patient/report metadata, not Q&A. Rendered by `renderPatientTable` (live) / `generateHeaderInfo` (dead code). Label is escaped; value is not.
+- **`data.wellbeing.calculation` / `.partsScore`** (Wellbeing) — pre-computed numeric scores. Rendered as score bars/gauges. N/A for escaping (numeric).
+- **`big_integral_questionnaire.js` internal `getDummyData()`** (Wellbeing, Maison Sante only) — hardcoded demo rows, **not real answers**. Rendered by `renderTable`.
+- **`data.SR.items[].biomarkerNote` / `.doctorNote` / `.insight`** (Wellbeing, SmartReport merge) — clinician notes on a lab value. Rendered by `renderReportItems`/`renderNoteV3` (`lib/template.js`). Escaping varies.
+- **`data.elements[]`** (Corporate) — pre-aggregated population analytics. Rendered by `renderBarChart` and table builders.
+- **`data.PartScoresHighestValues`, `data.insights.tips`** (SanusX) — pre-computed scores/flags. Rendered by the avatar/predictions/tips sections.
+
+## 5.4 Security note: unescaped answer text
+
+`renderDoctorDetails` (wellbeing `data.Profile`) injects `item.value` — and, in one further case, `item.title` — as raw HTML with no escaping. If any upstream system ever allows free-text answers containing HTML/script-like content to flow into this field unsanitized, that content will be injected verbatim into the rendered page before Puppeteer snapshots it to PDF. Because report generation happens server-side inside a headless Chrome instance (not a browser the end user controls), this is not a classic reflected-XSS-in-the-browser risk to the *end user*, but it is a real risk if payload data can come from a less-trusted source than the doctor/clinician — e.g. if patient-entered free text were ever passed straight through into `Profile[].value` without sanitization upstream. If you're auditing security boundaries, treat "who is allowed to populate `data.Profile`, and is it sanitized before it reaches this library" as an open question to raise with the host application team — this library does not sanitize it.