Documents Feature

Auto-generate professional consultation reports and prescriptions from appointment form data.

What this enables

Consultation reports: Specialist completes appointment form → system auto-generates branded PDF with findings, observations, and recommendations.

Prescriptions: Doctor fills prescription form (medication orders, PT exercises, rest recommendations) → auto-generate prescription PDF signed by specialist.

Private field filtering: Report shows diagnosis and notes to specialist, but patient PDF hides internal clinical notes—privacy automatically handled.

Digital signatures: Specialist's signature auto-embedded in generated PDF (image from their profile).

Compliance: Documents immutable after specialist signs—if you regenerate from same form data, PDF is identical. Audit trail of who created/signed.

How it works

Appointment created: System adds consultation report and prescription forms (if appointment template defines them)
Specialist fills form: Writes findings, recommendations, prescription orders
Form signed: Specialist reviews and signs form
PDF auto-generated: Uses PDF template + form data → creates professional PDF with clinic logo, findings, signature
Patient accesses: Logs in, downloads PDF report (private fields hidden)
Archived: PDF cached and immutable; always regenerates identically from signed form

Technical Reference

Overview

Reports and prescriptions are core outputs of the RestartiX platform. Every appointment can produce a report (consultation summary) and/or a prescription (treatment plan). This feature provides automated PDF generation from form data using a template-driven rendering system.

What Are Documents?

Documents in RestartiX are form-based outputs that transform structured appointment data into professional PDFs. Both reports and prescriptions are unified under the appointment_documents table, distinguished by a type column, but maintain separate business logic and regulatory requirements.

Document Type	Purpose	Who Creates	Regulatory
Report	Consultation summary, specialist observations, recommendations	Auto-created with appointment (from template)	Standard medical record retention
Prescription	Medication/treatment plan, actionable orders	Auto-created with appointment (from template)	Prescription regulations apply per jurisdiction

Key Features

Automated PDF Generation: On-demand generation from form data using chromedp (headless Chrome)
PDF Templates Integration: Uses the PDF Templates feature for visual template design with block-based editor
Audience Filtering: Different PDF views for patients (privacy-filtered) vs specialists/admins (full data)
Caching Strategy: Immutable signed documents cached to S3, preview PDFs generated on every request
Digital Signatures: Image-based specialist signatures embedded in PDFs
Form Integration: PDFs generated from signed form data with field validation

Design Principles

Form is the source of truth - Document content comes from forms.values and forms.fields. The document is a rendered view of form data, not a separate data entry point.
PDF Templates for layout - Visual layout comes from the PDF Templates feature. Form templates reference pdf_template_id to specify which PDF layout to use. Same form data can render with different PDF templates (standard report, certificate, detailed analysis, etc.).
Immutable after signing - Once a form is signed (status = 'signed'), the generated PDF is final. Re-generation from the same signed form must produce the identical document. The pdf_template_version is recorded to ensure consistent regeneration.
Private field filtering - Fields marked private: true are excluded from patient-facing PDFs but included in specialist/admin PDFs.
Synchronous generation, async optional - PDFs are generated on-demand when requested. No background job queue required initially.

Current State (Strapi)

Aspect	Current Implementation
Storage	`report` and `prescription` Strapi content types, each with `document` (single file) and `files` (multiple) media fields
Content	Form-based - each document references a `form` entity which holds field definitions and values
PDF generation	None. Specialists manually upload files or the frontend renders form data on screen
Signing	Strapi `draftAndPublish` sets `published_at`. No digital signatures
Specialist signature	Media file on `specialist.signature` - an uploaded image, not cryptographic
Template rendering	None. Form templates define fields, not visual layouts

Go Target Architecture

PDF Engine: chromedp (Headless Chrome)

The system uses chromedp for HTML-to-PDF conversion:

Full CSS/HTML support for pixel-perfect rendering
Handles complex layouts, tables, images, signatures
Supports embedded images (specialist signatures, logos, patient uploads)
Same Chrome rendering as browser previews
Container image: chromedp/headless-shell (~150MB)

Document Lifecycle

Appointment created with template
        │
        ▼
Form created (status=pending)
  ├─ Form template has pdf_template_id = 5
  └─ PDF template defines visual layout
        │
        ▼
Document exists (published=false, form attached)
        │
        ▼
Specialist/patient fills form (pending → in_progress → completed)
        │
        ▼
PDF preview available (live render using pdf_template, not cached)
        │
        ▼
Form signed (completed → signed, signed_at timestamp set)
        │
        ▼
Document generated
  ├─ Reads form.values and form.fields
  ├─ Merges with PDF template (id=5, version=3)
  ├─ Renders HTML → PDF via chromedp
  ├─ Records pdf_template_id=5, pdf_template_version=3
  └─ Uploads to S3
        │
        ▼
Published (published=true) - PDF cached to S3, template version locked

Patient Visibility Rules

Document State	Specialist/Admin	Patient
Form pending	Can view metadata	Can view metadata
Form in_progress	Can preview PDF	Cannot preview PDF
Form completed	Can preview PDF	Cannot preview PDF
Form signed, published=false	Can view final PDF	Cannot access PDF
Form signed, published=true	Can view final PDF	Can view final PDF (audience=patient forced)

Report vs. Prescription Differences

Aspect	Report	Prescription
Purpose	Consultation summary, specialist observations, recommendations	Medication/treatment plan, actionable orders
Who fills form	Specialist fills analysis fields, patient fills survey fields	Specialist only
Specialist signature	Included in PDF	Required in PDF - generation fails without it
Patient can download	Yes (when published, private fields excluded)	Yes (when published)
PDF audience filtering	Private fields excluded for patient audience	All fields visible to patient (prescription transparency)
Immutability	After form signing	After form signing
Multiple per appointment	No (UNIQUE constraint: one report per appointment)	No (UNIQUE constraint: one prescription per appointment)

Documentation

schema.sql - Database schema for appointment_documents and related tables
api.md - API endpoints for document operations and PDF generation
pdf-generation.md - PDF generation pipeline and engine details
templates.md - Template system, field placeholders, and customization
signatures.md - Digital signature handling and audit trail
caching.md - Performance optimization and cache invalidation

PDF Templates - Visual template designer for PDF layouts (block-based editor, Go template syntax, component library)
Forms - Source data for document generation (form templates link to PDF templates via pdf_template_id)
Appointments - Documents are attached to appointments

Custom Fields - Patient profile data accessible in PDF templates via {{.FormValues}}

Migration from Strapi

Data Migration Steps

pdf_templates: Create default report and prescription PDF templates per organization (via PDF Templates feature)
form_templates: Link form templates to PDF templates via pdf_template_id column
appointment_documents: Migrate existing reports and prescriptions Strapi content types to appointment_documents rows
Existing uploaded files: Copy report.document and report.files URLs to appointment_document_files
Form data: Handled by the form system migration - once forms are migrated, documents can generate PDFs using linked PDF templates

Backwards Compatibility

Existing manually-uploaded documents continue to work (served from appointment_document_files)
New documents get auto-generated PDFs via the pipeline
No breaking change - PDF generation is additive

Documents Feature ​

What this enables ​

How it works ​

Technical Reference ​

Overview ​

What Are Documents? ​

Key Features ​

Design Principles ​

Current State (Strapi) ​

Go Target Architecture ​

PDF Engine: chromedp (Headless Chrome) ​

Document Lifecycle ​

Patient Visibility Rules ​

Report vs. Prescription Differences ​

Documentation ​

Related Features ​

Migration from Strapi ​

Data Migration Steps ​

Backwards Compatibility ​