# 8. Known Issues & Technical Debt

Consolidated from all the research behind this documentation set, ranked roughly by how much time/pain each one can cost a new engineer. Each links to the doc section with full detail.

## Critical — will actively bite you

1. **`index.js` requires `lib/pdf_generator.min.js`, not `lib/pdf_generator.js`.** The two files have diverged independently since 2021 with no build step connecting them. Editing the readable source file silently does nothing. → [doc 1.4](01-architecture-overview.md#14-critical-fact-the-core-report-renderer-that-actually-runs-is-pdf_generatorminjs-not-pdf_generatorjs)
2. **SMTP credentials travel as plaintext JSON fields** inside a payload that's only base64-*encoded*, not encrypted. A logged request or an intercepted call leaks the SMTP password outright. → [doc 7.4](07-email-notifications.md#74-security-considerations)
3. **Client-name → config-file resolution is inconsistent across all five places that do it** (wellbeing generator, corporate generator, sendEmail, sanusx generator, core report which doesn't do it at all). Onboarding a new brand or debugging "why isn't my branding showing" requires checking the exact rule for the specific generator in use. → [doc 2.2](02-configuration-and-whitelabelling.md#22-how-clientclientname-resolves-to-a-config-file--and-why-its-inconsistent)
4. **`corporate_report_generator.js` lower-cases the client string before building a filename path**, but the actual `config/*.json` files are capitalized. Works today only because of case-insensitive filesystems (Windows/macOS); will silently fall back to `default.json` on Linux. → [doc 2.2](02-configuration-and-whitelabelling.md#22-how-clientclientname-resolves-to-a-config-file--and-why-its-inconsistent)
5. **`generateFullPdf`'s `showHeaderLogo || true` bug** — the header logo can never be suppressed regardless of what the caller passes. → [doc 4.B](04-report-pipelines.md#4b-wellbeing-report--optional-merged-smartreport)

## High — will cost real debugging time

6. **`sanusx_report_generator.js` ignores its `clientName` parameter for branding entirely** — always loads `config/sanusx.json`. Effectively single-brand despite accepting a client argument. → [doc 4.D](04-report-pipelines.md#4d-sanusx-report)
7. **SanusX RTL support is broken** — no `isRtl` flag is ever computed, the LTR template loads unconditionally, and the RTL template that does exist on disk references asset paths that don't exist under `assets/sanusx/`. → [doc 4.D](04-report-pipelines.md#4d-sanusx-report)
8. **SanusX's PDF is hard-limited to one page** (`pageRanges: '1'`) — any overflow is silently dropped, not pushed to page 2. → [doc 4.D](04-report-pipelines.md#4d-sanusx-report)
9. **`lib/big_integral_questionnaire.js` renders 100% hardcoded dummy data**, not real patient answers. Easy to mistake for a real, working feature. → [doc 4.B.1](04-report-pipelines.md#4b1-libbig_integral_questionnairejs--read-this-before-assuming-its-a-real-feature)
10. **Locale state is a process-global mutable singleton** (`i18n.setLocale(...)` mutates a shared, cached module). Concurrent report-generation calls in the same process can leak one request's language into another's render. The codebase already had to specifically patch around an analogous bug for temp-file paths (`generateFullPdf`'s UUID scheme) but never applied the same fix to locale state. → [doc 6.6](06-internationalization.md#66-gotchas-for-a-new-engineer)
11. **Older flows (`generateMedicusPDF`, `generateNascoPDF`, `generateSanuxPDF`) write to fixed, shared filenames under `output/`** with no cleanup — concurrent requests can clobber each other's files, and disk usage grows unbounded over time. Only `generateFullPdf` was hardened with per-call UUID temp paths + cleanup. → [doc 1.7](01-architecture-overview.md#17-filetemp-file-handling--an-evolving-pattern-worth-knowing)
12. **`LocaleService.setLocale()` silently no-ops on an unsupported locale** instead of falling back to English like the underlying package would — the previously active locale on the shared singleton just stays in effect. → [doc 6.5](06-internationalization.md#65-fallback-logic--two-layers-that-disagree)
13. **`renderDoctorDetails` (wellbeing `data.Profile`) does not HTML-escape answer values** — a real risk if any upstream source of Q&A text isn't already sanitized. → [doc 5.4](05-questions-and-data-model.md#54-security-note-unescaped-answer-text)

## Medium — worth fixing, lower urgency

14. **No fallback from a brand template folder to shared `templates/blocks/`** for individual missing blocks — the "extended" wellbeing flow throws `ENOENT` if a client folder is incomplete or missing entirely; only `Mediclinic`, `Pha`, `maisonsante` are supported today. → [doc 2.4](02-configuration-and-whitelabelling.md#24-template-folder-selection--no-blocks-level-fallback)
15. **Two independent copies of Chart.js** (npm `chart.js`, unused/dead server-side import, vs. bundled `assets/charts.min.js`, actually used client-side inside headless Chrome) can silently drift out of version sync. → [doc 3.4](03-templating-and-rendering.md#34-charts)
16. **`generatePatientQR`/`generateQrCode` doesn't generate QR codes** — it's a generic "rasterize this HTML string" utility; the caller must pre-render the QR (e.g. as inline SVG) before calling it. Misleading name. → [doc 3.5](03-templating-and-rendering.md#35-qr-codes--two-unrelated-mechanisms)
17. **Orphaned/dead locale files**: `locales/ar.json` (wrong schema for its directory, not in the configured locales list) and `locales/wellbeing/it-IT.json` (not in the configured locales list). → [doc 6.6](06-internationalization.md#66-gotchas-for-a-new-engineer)
18. **`ar-AE` is functionally unreachable** in three of the four generators — RTL detection coerces any `"ar"`-containing language straight to `ar-SA`. → [doc 6.4](06-internationalization.md#64-rtl-handling--three-overlapping-mechanisms)
19. **Auto-write-on-missing-key behavior** (`i18n`'s `updateFiles: true` default) has already silently written malformed entries into `locales/wellbeing/en.json` (bare strings instead of `{message, description}` objects) from a currently-unused lookup path — a landmine if that lookup is ever wired up for real. → [doc 6.5](06-internationalization.md#65-fallback-logic--two-layers-that-disagree)
20. **Corporate report has a live external CDN dependency at render time** (`page.addScriptTag({ url: 'https://cdn.jsdelivr.net/...' })`) — unlike the other three pipelines, which bundle their own JS/CSS locally. A network outage or CDN change could break corporate-report generation specifically. → [doc 4.C](04-report-pipelines.md#4c-corporate-report)
21. **Onboarding a new brand's corporate-report cover background requires editing shared CSS by client-name selector** (`.cover-overlay-container.bionext {...}`), bypassing the config-JSON theming model otherwise used everywhere else. → [doc 4.C](04-report-pipelines.md#4c-corporate-report)
22. **Corporate/SanusX translation strings live in the `locales/wellbeing/` bucket**, not a dedicated namespace, despite neither product being "wellbeing." → [doc 6.1](06-internationalization.md#61-library-and-the-two-independent-configurations)
23. **`sendNascoEmail` is reused across wellbeing, extended-wellbeing, and SanusX flows** despite its Nasco-specific name — a shared helper with a misleading, client-specific name baked into common infrastructure. → [doc 7.1](07-email-notifications.md#71-module-and-exports)
24. **Dead code accumulation**: unused `templates/base.html`/`template.html`/`ltr.html`/`no_pages.html`/`empty.html`/`first_page_head.html`; `templates/popup/popup-template.html` (unreferenced anywhere); `templates/sanusx/blocks/tips.html` (unreferenced — a different `tips.html` under `templates/wellbeing/blocks/` is the one actually read); `combinePDFBuffers`/`isEmpty` copy-pasted but unused in `corporate_report_generator.js`; `generateHeaderInfo()`'s output computed but discarded (target selector commented out); `historyData` always an empty array, returned but never populated, across all three non-core generators; dead `chart.js`/`qr-image`/`qrcode` npm imports server-side. None of these are actively harmful, but they add noise when searching the codebase and should be pruned opportunistically.
25. **`mailConfig.secure` is collected from every caller but never read** by the actual transport — dead parameter, misleading API surface. → [doc 7.2](07-email-notifications.md#72-smtp-transport-configuration--entirely-caller-supplied)

## Suggested first fixes if you're picking one place to start

If asked to spend a day improving this codebase's reliability rather than adding features, the highest-leverage fixes are (1) wiring an actual build step (or simply deleting `pdf_generator.js` and renaming `.min.js`) to remove the source/runtime divergence risk, (3)/(4) unifying client-name resolution into one shared helper function used by all five call sites, and (10) scoping locale state per-request instead of relying on a shared singleton.