TX Dynamics · Technical Handoff

Vicus "My Vicus / Add Documents" — Document-Viewer Fix

Fix the black-background document viewer in the mein-vicus module and ship it safely to production — without regressing the live site.

Prepared by · TX Dynamics Assigned to · Wajeeh (proposed) Date · 2026-06-30 Project · Vicus (vicus.online) Type · Production bug fix + deploy
Confidential — internal technical handoff. No commercial / pricing detail.
4
Verfügung templates in scope
~15lines
Core server-side fix
~1.5–2d
Suggested effort (to confirm)
0
Frontend changes required

1. Objective

Fix the bug where documents saved under "My Vicus → Add Documents" display with a black background / white text instead of the correct white background, black text, with the user's signature — and deliver the fix to production (live) without regressing existing functionality.

2. Background — the feature
Module
  • Module: mein-vicus/ (custom PHP + dompdf, behind an app.js SPA).
  • The 4 templates: Vorsorgevollmacht, Patientenverfügung, Generalvollmacht, Betreuungsverfügung. (Organspendeausweis is a separate card graphic — not in scope.)

Generate — mein-vicus/assets/scanner.js → saveVerfuegung():

POST route=save_organ_card→ api/index.php (case save_organ_card)→ build HTML→ dompdf → PDF→ DB vicus_documents

POSTs export_format:'pdf' + signature_data → the PDF is stored at mein-vicus/storage/scans/<uid>/verfuegung_*.pdf.

Display — mein-vicus/assets/app.js → showDocument() renders each page as <img src="…/api/index.php?route=document_file&id=X&page=N"> inside a near-black (#020617) container → route=document_file → handleDocumentFile() (api/index.php, ~line 1197) serves the raw stored file (no PDF→image step).

3. Root cause (already diagnosed — read-only)

The viewer renders every page in an <img> tag, but generation now outputs a PDF. A PDF cannot render inside <img> → broken image → the dark container shows through = the "black background" the client sees. (A prior switch of generation to PDF silently broke the in-app preview.)

What's actually fine vs. broken
  • Verified: PDF generation itself is correct — a dummy-data render of the current live template = white bg, black text, signature + signature line. The document content is fine; only the display is broken.
  • Secondary case to handle: some older documents are genuine dark image snapshots (the pre-PDF html2canvas PNG method). Those are literally dark pixels — the viewer fix will not fix them; they must be regenerated / migrated.

4. Scope (in scope)
  1. Primary fix — in handleDocumentFile() (mein-vicus/api/index.php): when the stored file is a PDF, render the requested page to a white-background PNG on demand and serve image/png. Use pdftoppm -png -r 150 -f N -l N or convert -density 150 -background white -flatten (both present on the server). Make the documents-list response report the PDF's real page count so the viewer loops pages correctly. Cache the rendered PNG (e.g. beside the source PDF) to avoid re-rendering on every load. ~15 lines, no frontend change required.
    • Acceptable alternative: change the frontend viewer to embed PDFs via <iframe>/<embed>. The server-side single-point fix is cleaner and preferred.
  2. Old-document handling — identify documents stored as dark PNG snapshots and regenerate them (or provide a migration) so existing affected docs also display correctly. Confirm the affected count with the client.
  3. Deploy to live — ship the fix to production via the approved process without regressing existing fixes (see §6 + §7).
  4. Regression test — verify the whole document area still works: scan upload, organ-card, OCR, share.

5. Out of scope
  • The larger Vicus + Mecam review/sync project (shared login/payment, billing model, 18+, mobile apps).
  • Any feature change beyond the document-viewer fix and the old-document cleanup.

6. Environment, access & golden rules
Environment
  • Server: Hetzner, SSH user vicus (sudo + www-data). SSH/DB credentials are in the Entwickler-Zugang-Server PDF — provided separately and securely. Do NOT store credentials in this doc, any chat, or any repo.
  • Stack: custom PHP, Nginx + PHP-FPM + MariaDB, dompdf; app.js SPA.
  • Paths: Vicus live /var/www/vicus/ · staging /var/www/vicus-staging/. (Mecam: live /var/www/html/ · staging /var/www/html-staging/.)
  • Tools available on server: pdftoppm, gs, convert, pdfinfo.

Golden rules (client's — mandatory):

  • 🚫 Never edit live directly. Work on staging.
  • Deploy only via /usr/local/bin/vicus-deploy.sh [vicus|mecam|all] (auto-backups).
  • Regression-test all existing features after deploy.
  • vendor/autoload.php is hardcoded to /var/www/vicus/vendor/ (live) and is required even from staging code — note this coupling.

7. ⚠️ KEY RISK — the deploy (read before deploying)
⚠️ Staging is significantly diverged from live — and live is AHEAD of staging on a recent fix.

A wholesale staging→live deploy would regress live and ship unrelated work-in-progress. Specifically:

  • Live's PDF generation already forces white bg (background:#fff !important; color:#1e293b !important). Staging does NOT have this → deploying staging→live would undo the client team's own fix.
  • scanner.js differs by ~1,900 lines (someone's WIP), app.js ~176, api/index.php ~23.

Before any live deploy you MUST reconcile staging ↔ live. First confirm with the client's team (Sammy / @enusys.de): whose is the ~1,900-line scanner.js WIP on staging, and can it be discarded? Then either:

  • (a) sync staging from live, apply only this fix on top, test, deploy via the script; or
  • (b) apply the single isolated handleDocumentFile change directly to live with a backup — only with the client's explicit OK, as a one-off exception to the staging-only rule (smallest blast radius: one function).

Do NOT blind-deploy the whole site.

8. Acceptance criteria (definition of done)
  1. On a test account: generate a new Verfügung → view it → it shows white bg, black text, signature (no black box).
  2. Existing PDFs render correctly via the fix; old dark-PNG snapshots are regenerated / handled.
  3. No regression to live's existing white-bg generation fix or other document features (scan / organ-card / OCR / share all still work).
  4. Fix is live on production, deployed via the approved process; client (Martin) can confirm in the app.

9. Deliverables
What ships
  • The fix deployed on live (Vicus production).
  • Short before/after evidence on a test document + a note on how old documents were handled.
  • The code diff/patch for the client's records if requested.

10. Suggested effort (developer to confirm)

Roughly ~1.5–2 working days — the fix itself is small; the deploy reconciliation (staging/live divergence) is the variable. Confirm your own estimate before starting.

11. References (TX-internal, not for the client)
  • Diagnosis: diagnosis-document-template-bug-2026-06-29.md
  • Developer brief: DEV-BRIEF-doc-viewer-fix.md