Polaris Clinical Document Architecture - Design Document¶

THIS IS A DRAFT PROPOSAL - NOT YET APPROVED FOR PRODUCTION USE

Date: July 23, 2025
Version: 2.0
Status: Draft - Major Revision
Purpose: Define FHIR R4 profiles for comprehensive clinical document architecture supporting three distinct section types with recursive containment

Executive Summary¶

This design document specifies a FHIR R4-based clinical document architecture for the Polaris implementation guide. The solution addresses user requirements for a universal, interoperable document model that can represent "every kind of EMR form" with graceful degradation across different EMR systems.

Key Design Principles¶

Bundle-based Document Model: All documents are FHIR Bundles starting with a Composition resource
Three Section Types: Text, Questionnaire/Form, and Canvas sections with recursive containment
Flexible Section Architecture: Multiple sections of each type allowed in any order
Universal Translation Target: Rich enough to capture diverse EMR content, with fallback strategies
File Attachment Support: Arbitrary file attachments supported alongside structured content
Canadian Standards Alignment: Consistent with CA-Core+, CABase, PSCA, and provincial implementations using standard LOINC codes

Architecture Overview¶

Core Resource Model¶

PolarisCoreDocumentBundle (Bundle)
├── PolarisCoreComposition (first entry, required)
├── Supporting Resources (Patient, Practitioner, etc.)
├── Section-specific Resources (multiple of each type, any order):
    ├── Text Sections: Embedded in Composition.section.text (LOINC: 34109-9)
    ├── Form Sections: Questionnaire + QuestionnaireResponse (LOINC: 74468-0/74465-6)
    ├── Canvas Sections: DocumentReference + Extensions (LOINC: 11540-0)
    └── File Attachment Sections: DocumentReference (any MIME type)

Section Type Architecture¶

Section Type	Primary FHIR Resource	Content Format	LOINC Code	Embedding Support
Text	Composition.section.text	XHTML + Markdown extension	34109-9 "Note"	Structured data pills, inline forms, canvas elements
Questionnaire/Form	Questionnaire + QuestionnaireResponse	Name-value pairs, single column layout	74468-0/74465-6	References to other sections
Canvas	DocumentReference + Extensions	Images, PDFs, drawings, signatures	11540-0 "Image"	Coordinate-based overlays
File Attachment	DocumentReference	Any MIME type, arbitrary files	Standard document codes	Referenced from other sections

Detailed FHIR Profile Specifications¶

1. PolarisCoreDocumentBundle Profile¶

Parent: Bundle
Canonical URL: https://fhir.apps.health/StructureDefinition/polaris-core-document-bundle

Key Constraints:¶

Bundle.type = "document" (fixed)
First entry must be PolarisCoreComposition
All referenced resources must be included (Bundle integrity)
Support for versioning through Bundle.identifier and timestamp

Bundle Entry Requirements:¶

Entry[0]: PolarisCoreComposition (required)
Entry[1..n]: Referenced resources (Patient, Practitioner, Organization, etc.)
Entry[n+1..m]: Section-specific resources (Questionnaire, DocumentReference, etc.)

2. PolarisCoreComposition Profile¶

Parent: Composition
Canonical URL: https://fhir.apps.health/StructureDefinition/polaris-core-composition

Core Elements:¶

identifier: Business identifier for document version tracking
status: Document lifecycle status (preliminary, final, amended, corrected)
type: Document type (LOINC-coded, extensible binding)
subject: Reference to PolarisCorePatient
date: Document creation/last modified timestamp
author: Reference to Practitioner/PractitionerRole/Device/Organization
title: Human-readable document title
confidentiality: Security classification
section: Hierarchical sections supporting four distinct types, multiple of each allowed in any order

Section Structure:¶

* section 0..* MS
* section ^slicing.discriminator.type = #value
* section ^slicing.discriminator.path = "code.coding.code"
* section ^slicing.rules = #open

// Text Section Slice - Multiple allowed
* section contains textSection 0..*
* section[textSection].code = http://loinc.org#34109-9 "Note"
* section[textSection].text 1..1 MS  
* section[textSection].text.div 1..1 MS  // XHTML content
* section[textSection] obeys polaris-text-section-constraints
* section[textSection].extension contains PolarisMarkdownExtension named markdown 0..1

// Form Section Slice - Multiple allowed
* section contains formSection 0..*
* section[formSection].code from PolarisFormSectionCodes (required)
* section[formSection].entry 1..* MS
* section[formSection].entry only Reference(PolarisQuestionnaire or PolarisQuestionnaireResponse)

// Canvas Section Slice - Multiple allowed  
* section contains canvasSection 0..*
* section[canvasSection].code = http://loinc.org#11540-0 "Image"
* section[canvasSection].entry 1..* MS
* section[canvasSection].entry only Reference(PolarisCanvasDocumentReference)

// File Attachment Section Slice - Multiple allowed
* section contains attachmentSection 0..*
* section[attachmentSection].code from PolarisAttachmentSectionCodes (extensible)
* section[attachmentSection].entry 1..* MS
* section[attachmentSection].entry only Reference(PolarisFileAttachmentDocumentReference)

// Value Sets for Section Codes
ValueSet: PolarisFormSectionCodes
Id: polaris-form-section-codes
* http://loinc.org#74468-0 "Questionnaire form definition Document"
* http://loinc.org#74465-6 "Questionnaire response Document"

ValueSet: PolarisAttachmentSectionCodes  
Id: polaris-attachment-section-codes
* http://loinc.org#18842-5 "Discharge summary"
* http://loinc.org#11492-6 "History and physical note"
* http://loinc.org#28570-0 "Procedure note"
* http://loinc.org#34133-9 "Summary of episode note"

3. Text Section Extensions¶

PolarisMarkdownExtension¶

URL: https://fhir.apps.health/StructureDefinition/polaris-markdown-content Context: Composition.section.text Purpose: Provide Markdown version alongside XHTML

Extension: PolarisMarkdownExtension
Id: polaris-markdown-content
Title: "Polaris Markdown Content Extension"
Description: "Provides Markdown representation of text content for systems supporting markdown rendering"
* ^context.type = #element
* ^context.expression = "Composition.section.text"
* value[x] only markdown
* valueMarkdown 1..1 MS

PolarisEmbeddedSectionExtension¶

URL: https://fhir.apps.health/StructureDefinition/polaris-embedded-section Context: Composition.section.text.div (on span elements) Purpose: Embed complete sections of any type within text content

Extension: PolarisEmbeddedSectionExtension
Id: polaris-embedded-section
Title: "Polaris Embedded Section Extension"
Description: "Embeds complete Polaris sections (Text/Form/Canvas/File) within text content as actual nested content"
* ^context.type = #element
* ^context.expression = "Element"  // Applied to span/div elements in XHTML
* extension contains
    embeddedSectionType 1..1 MS and
    embeddedSectionContent 1..1 MS and
    displayHint 0..1 MS and
    fallbackText 0..1 MS
* extension[embeddedSectionType].value[x] only code
* extension[embeddedSectionType].valueCode from PolarisEmbeddedSectionTypes (required)
* extension[embeddedSectionContent].value[x] only Composition.section
* extension[displayHint].value[x] only string
* extension[fallbackText].value[x] only string

ValueSet: PolarisEmbeddedSectionTypes
Id: polaris-embedded-section-types
* #text-section "Embedded Text Section"
* #form-section "Embedded Form Section"
* #canvas-section "Embedded Canvas Section"
* #attachment-section "Embedded File Attachment Section"

4. Form Section Profiles¶

PolarisQuestionnaire Profile¶

Parent: Questionnaire
Canonical URL: https://fhir.apps.health/StructureDefinition/polaris-questionnaire

Key Constraints:¶

Must include version for consistency with bundled responses
Support for single-column layout hint
Extended item types for clinical data
Support for embedded sections as answer values
Recursive containment of any section type

Profile: PolarisQuestionnaire
Parent: Questionnaire
* version 1..1 MS  // Required for version pinning
* item MS
* item.type MS
* item.type from PolarisQuestionnaireItemTypes (extensible)
* item.text 1..1 MS
* item.answerOption.value[x] MS
// Support for embedded sections in answer options
* item.answerOption.extension contains PolarisEmbeddedSectionAnswerExtension named embeddedSection 0..1
// Extension for layout hints
* item.extension contains PolarisLayoutHintExtension named layoutHint 0..1

ValueSet: PolarisQuestionnaireItemTypes
Id: polaris-questionnaire-item-types
* Questionnaire.item.type#string "String"
* Questionnaire.item.type#text "Text"
* Questionnaire.item.type#boolean "Boolean"
* Questionnaire.item.type#decimal "Decimal"
* Questionnaire.item.type#integer "Integer"
* Questionnaire.item.type#date "Date"
* Questionnaire.item.type#dateTime "DateTime"
* Questionnaire.item.type#choice "Choice"
* Questionnaire.item.type#open-choice "Open Choice"
* #embedded-section "Embedded Section" // New type for section containment

Extension: PolarisEmbeddedSectionAnswerExtension
Id: polaris-embedded-section-answer
Title: "Polaris Embedded Section Answer Extension"
Description: "Allows questionnaire answer options to contain complete embedded sections"
* ^context.type = #element
* ^context.expression = "Questionnaire.item.answerOption"
* value[x] only Composition.section

PolarisQuestionnaireResponse Profile¶

Parent: QuestionnaireResponse
Canonical URL: https://fhir.apps.health/StructureDefinition/polaris-questionnaire-response

Key Features:¶

Mandatory reference to specific Questionnaire version
Support for embedded sections as actual answer values
Clinical value type validation
Recursive containment support in responses

Profile: PolarisQuestionnaireResponse
Parent: QuestionnaireResponse
* questionnaire 1..1 MS  // Must reference specific version
* questionnaire only Canonical(PolarisQuestionnaire)
* item.answer.value[x] MS
// Standard FHIR answer types
* item.answer.value[x] ^type[+].code = #string
* item.answer.value[x] ^type[+].code = #boolean
* item.answer.value[x] ^type[+].code = #decimal
* item.answer.value[x] ^type[+].code = #integer
* item.answer.value[x] ^type[+].code = #date
* item.answer.value[x] ^type[+].code = #dateTime
* item.answer.value[x] ^type[+].code = #Coding
// Extended to support embedded sections as answer values
* item.answer.extension contains PolarisEmbeddedSectionResponseExtension named embeddedSectionAnswer 0..1

Extension: PolarisEmbeddedSectionResponseExtension
Id: polaris-embedded-section-response
Title: "Polaris Embedded Section Response Extension"
Description: "Contains complete sections as questionnaire response values"
* ^context.type = #element
* ^context.expression = "QuestionnaireResponse.item.answer"
* value[x] only Composition.section

5. Canvas Section Profiles¶

PolarisCanvasDocumentReference Profile¶

Parent: DocumentReference
Canonical URL: https://fhir.apps.health/StructureDefinition/polaris-canvas-document-reference

Enhanced Features:¶

Support for multiple content formats (images, PDFs)
Coordinate-based annotation overlays with embedded sections
Drawing and signature capabilities
PDF import with component positioning
Recursive section embedding at specific coordinates

Profile: PolarisCanvasDocumentReference
Parent: DocumentReference
* content 1..* MS
* content.attachment.contentType from PolarisCanvasContentTypes (extensible)
* content.attachment.data 1..1 MS
// Extension for canvas-specific metadata and embedded sections
* extension contains 
    PolarisCanvasMetadataExtension named canvasMetadata 0..1 MS and
    PolarisCanvasAnnotationExtension named annotations 0..* MS

PolarisCanvasMetadataExtension¶

Purpose: Canvas dimensions, coordinate system, PDF page mapping

Extension: PolarisCanvasMetadataExtension
Id: polaris-canvas-metadata
* extension contains
    width 0..1 MS and
    height 0..1 MS and
    coordinateSystem 0..1 MS and
    pdfPageNumber 0..1 MS
* extension[width].value[x] only positiveInt
* extension[height].value[x] only positiveInt
* extension[coordinateSystem].value[x] only code
* extension[coordinateSystem].valueCode from PolarisCoordinateSystems (required)

PolarisCanvasAnnotationExtension¶

Purpose: Drawings, signatures, positioned form elements, AND embedded sections at coordinates

Extension: PolarisCanvasAnnotationExtension
Id: polaris-canvas-annotation
Title: "Polaris Canvas Annotation Extension"
Description: "Supports drawings, signatures, positioned elements, and embedded complete sections at specific coordinates on canvas"
* extension contains
    annotationType 1..1 MS and
    coordinates 1..1 MS and
    content 0..1 MS and
    embeddedSection 0..1 MS and
    style 0..1 MS
* extension[annotationType].value[x] only code
* extension[annotationType].valueCode from PolarisCanvasAnnotationTypes (required)
* extension[coordinates].value[x] only string  // JSON coordinate data
* extension[content].value[x] only string  // For simple text/drawing content
* extension[embeddedSection].value[x] only Composition.section  // For embedded sections
* extension[style].value[x] only string  // CSS-like styling

ValueSet: PolarisCanvasAnnotationTypes
Id: polaris-canvas-annotation-types
Title: "Polaris Canvas Annotation Types"
Description: "Types of annotations that can be placed on canvas sections"
* #drawing "Drawing" "Freehand drawing or sketch"
* #signature "Signature" "Digital signature"
* #text "Text" "Text annotation"
* #shape "Shape" "Geometric shape"
* #embedded-text-section "Embedded Text Section" "Complete text section at coordinates"
* #embedded-form-section "Embedded Form Section" "Complete questionnaire/form at coordinates"  
* #embedded-canvas-section "Embedded Canvas Section" "Nested canvas section at coordinates"
* #embedded-attachment-section "Embedded File Section" "File attachment reference at coordinates"

6. File Attachment Section Profiles¶

PolarisFileAttachmentDocumentReference Profile¶

Parent: DocumentReference
Canonical URL: https://fhir.apps.health/StructureDefinition/polaris-file-attachment-document-reference

Key Features:¶

Support for arbitrary file types and MIME types
File metadata preservation (size, creation date, etc.)
Integration with other section types through references
Fallback display strategies for unsupported formats

Profile: PolarisFileAttachmentDocumentReference
Parent: DocumentReference
Id: polaris-file-attachment-document-reference
Title: "Polaris File Attachment DocumentReference Profile"
Description: "Profile for arbitrary file attachments in clinical documents, supporting any MIME type with appropriate metadata"

* content 1..1 MS
* content.attachment 1..1 MS
* content.attachment.contentType 1..1 MS  // Any MIME type allowed
* content.attachment.data 0..1 MS  // Base64 data or URL
* content.attachment.url 0..1 MS   // Alternative to embedded data
* content.attachment.size 0..1 MS
* content.attachment.hash 0..1 MS  // For integrity checking
* content.attachment.title 0..1 MS
* content.attachment.creation 0..1 MS

// Extension for file metadata
* extension contains PolarisFileMetadataExtension named fileMetadata 0..1 MS

// Must reference subject patient
* subject 1..1 MS
* subject only Reference(PolarisCorePatient)

PolarisFileMetadataExtension¶

Purpose: Additional file metadata and display hints

Extension: PolarisFileMetadataExtension
Id: polaris-file-metadata
Title: "Polaris File Metadata Extension"
Description: "Additional metadata for file attachments including display hints and processing instructions"

* extension contains
    originalFileName 0..1 MS and
    fileCategory 0..1 MS and
    displayHint 0..1 MS and
    processingInstructions 0..1 MS and
    embeddedSections 0..* MS

* extension[originalFileName].value[x] only string
* extension[fileCategory].value[x] only code
* extension[fileCategory].valueCode from PolarisFileCategories (extensible)  
* extension[displayHint].value[x] only string
* extension[processingInstructions].value[x] only string
* extension[embeddedSections].value[x] only Composition.section

// Value set for file categories
ValueSet: PolarisFileCategories
Id: polaris-file-categories
Title: "Polaris File Categories"
Description: "Categories for file attachments to aid in processing and display"
* ^status = #draft
* #document "Document" "Text-based document (PDF, DOC, etc.)"
* #image "Image" "Image file (JPEG, PNG, etc.)"
* #audio "Audio" "Audio recording"
* #video "Video" "Video recording"  
* #data "Data" "Structured data file (XML, JSON, CSV, etc.)"
* #archive "Archive" "Compressed archive (ZIP, TAR, etc.)"
* #other "Other" "Other file type"

Clinical Form Library Architectures and Mapping Strategies¶

This section comprehensively describes every conceivable architecture for clinical form libraries and how they map to and from the Polaris clinical document architecture. The goal is to ensure Polaris can serve as a universal translation target for any clinical form system.

1. Static Layout Form Architectures¶

1.1 Native Mobile/Desktop App Forms¶

Architecture: Fixed pixel-positioned UI controls with predefined layouts - Components: Buttons, text fields, checkboxes, dropdowns, sliders - Layout: Absolute positioning, fixed screen sizes, platform-specific controls - Data: Structured JSON/XML with field IDs and values

Mapping to Polaris: - Form Section: Use Questionnaire with PolarisLayoutHintExtension for positioning - Canvas Section: Screenshot of form layout as background image with coordinate overlays - Text Section: Fallback narrative description of form content

Mapping from Polaris: - Questionnaire → Native Controls: Map item types to platform controls - Canvas Annotations → Positioning: Use coordinates for control placement - Embedded Sections → Sub-forms: Recursive form generation

1.2 Web Form Libraries (React, Angular, Vue Components)¶

Architecture: Component-based forms with CSS styling and responsive layouts - Components: Reusable form components, validation libraries, state management - Layout: CSS Grid/Flexbox, responsive breakpoints, theme systems - Data: Component props, state objects, validation schemas

Mapping to Polaris: - Form Section: Questionnaire items map to component props - Text Section: CSS styles embedded as processing instructions - Canvas Section: Complex layouts rendered as images with hotspots - File Attachment: Component library exports (JSON schemas)

Mapping from Polaris: - Questionnaire → Components: Generate component trees from item hierarchy - Embedded Sections → Compound Components: Recursive component composition - Canvas Overlays → CSS Positioning: Convert coordinates to CSS transforms

2. Document-Based Form Architectures¶

2.1 Text Document Forms (Word, Google Docs)¶

Architecture: Document-based forms with fillable fields embedded in rich text - Components: Text boxes, checkboxes, dropdown lists, tables - Layout: Flow-based layout, page breaks, section headers - Data: Mail merge fields, form field references, document properties

Mapping to Polaris: - Text Section: Document content as XHTML with embedded form fields - Form Section: Extract fillable fields as Questionnaire items - File Attachment: Original document preserved with metadata - Canvas Section: Document rendered as images with form field overlays

Mapping from Polaris: - Text + Form → Document: Generate document template with mail merge fields - Embedded Sections → Document Sections: Map to document headings/sections - Canvas Annotations → Comments: Convert to document review comments

2.2 PDF Form Architectures¶

Architecture: PDF documents with interactive form fields and JavaScript behaviors - Components: PDF form fields (text, choice, signature), JavaScript actions - Layout: Fixed page layouts, absolute positioning, print-optimized - Data: PDF form data (FDF/XFDF), field dictionaries, annotation streams

Mapping to Polaris: - Canvas Section: PDF pages as images with field position metadata - Form Section: PDF form fields as Questionnaire items with coordinates - File Attachment: Original PDF with form field extraction metadata - Text Section: Extracted text content with field placeholders

Mapping from Polaris: - Canvas + Form → PDF: Generate PDF with form fields at specified coordinates - Embedded Sections → PDF Layers: Create layered PDF with section groups - Questionnaire → PDF Forms: Map item types to PDF field types

2.3 Scanned Paper Form Architectures¶

Architecture: Paper forms digitized through scanning with OCR and field recognition - Components: Scanned images, OCR text regions, checkbox recognition - Layout: Fixed paper dimensions, handwriting recognition zones - Data: OCR confidence scores, field boundary boxes, extracted text

Mapping to Polaris: - Canvas Section: Scanned form images with OCR-derived field overlays - Form Section: Recognized fields as Questionnaire items with confidence scores - Text Section: OCR text with uncertainty annotations - File Attachment: Original scan files with processing metadata

Mapping from Polaris: - Canvas → Print Template: Generate printable forms from canvas layouts - Form → Field Recognition: Provide field templates for future scanning - Text → OCR Validation: Use narrative text for OCR accuracy checking

3. Custom Form Engine Architectures¶

3.1 Absolute Positioning Form Engines¶

Architecture: Custom form builders with pixel-perfect positioning and complex layouts - Components: Drag-drop form designer, custom widgets, complex validation rules - Layout: Absolute X,Y positioning, z-index layering, responsive containers - Data: Form definition JSON, widget libraries, custom JavaScript behaviors

Mapping to Polaris: - Canvas Section: Form background/template with precise field positioning - Form Section: Field definitions with exact coordinate metadata - Text Section: Form instructions and help text with positioning hints - File Attachment: Custom widget definitions and JavaScript libraries

Mapping from Polaris: - Canvas + Form → Form Engine: Reconstruct form with exact positioning - Embedded Sections → Nested Widgets: Create compound custom widgets - Coordinates → Pixel Positioning: Direct mapping of canvas coordinates

3.2 Dynamic Layout Form Engines¶

Architecture: Forms generated from field lists with automatic layout algorithms - Components: Field type libraries, layout managers, responsive containers - Layout: Algorithm-driven positioning, responsive grids, automatic spacing - Data: Field definitions, layout rules, conditional logic, validation schemas

Mapping to Polaris: - Form Section: Direct mapping to Questionnaire items with layout hints - Text Section: Form descriptions and conditional logic as narrative - Canvas Section: Layout screenshots for complex arrangements - File Attachment: Layout rule engines and field libraries

Mapping from Polaris: - Questionnaire → Dynamic Layout: Use layout hints to guide algorithms - Embedded Sections → Sub-forms: Recursive layout generation - Text Instructions → Conditional Logic: Parse narrative for form rules

3.3 Flow-Based Form Architectures¶

Architecture: Multi-step forms with branching logic and conditional flows - Components: Step definitions, flow charts, conditional branches, progress tracking - Layout: Wizard interfaces, progress bars, step navigation - Data: Flow state machines, branching conditions, step completion tracking

Mapping to Polaris: - Form Section: Each step as separate Questionnaire with flow metadata - Text Section: Flow instructions and step descriptions - Canvas Section: Flow diagrams and step visualizations - Multiple Sections: Each flow step as separate section in sequence

Mapping from Polaris: - Multiple Form Sections → Flow Steps: Reconstruct flow from section sequence - Embedded Sections → Sub-flows: Create nested flow branches - Questionnaire Logic → Conditions: Map skip patterns to flow branches

4. Multimedia Form Architectures¶

4.1 Video/Audio Form Architectures¶

Architecture: Forms integrated with multimedia content for training or assessment - Components: Video players, audio controls, synchronized form fields, timestamps - Layout: Media players with overlay forms, timeline scrubbing, chapter markers - Data: Media files, timestamp markers, synchronized responses, media metadata

Mapping to Polaris: - Canvas Section: Video frames with timestamp-based form overlays - Form Section: Time-synchronized questions with media cues - File Attachment: Media files with synchronization metadata - Text Section: Transcripts and media descriptions

Mapping from Polaris: - Canvas + Form → Multimedia: Synchronize questions with media timeline - File Attachments → Media: Embed media with form interaction points - Timestamps → Questionnaire Logic: Create time-based conditional logic

4.2 3D/VR Form Architectures¶

Architecture: Forms in virtual or augmented reality environments - Components: 3D models, spatial interfaces, gesture controls, head tracking - Layout: 3D positioning, spatial relationships, immersive environments - Data: 3D coordinates, orientation data, gesture events, spatial annotations

Mapping to Polaris: - Canvas Section: 3D environment screenshots with spatial overlays - Form Section: Spatial interactions as specialized Questionnaire items - File Attachment: 3D models and VR environment definitions - Text Section: Spatial instructions and environment descriptions

Mapping from Polaris: - Canvas Coordinates → 3D Space: Convert 2D coordinates to 3D positioning - Embedded Sections → Spatial Zones: Create interactive 3D regions - Form Logic → Spatial Triggers: Map questionnaire logic to spatial events

5. Specialized Clinical Form Architectures¶

5.1 Medical Device Integration Forms¶

Architecture: Forms that interface directly with medical devices for real-time data - Components: Device connectors, real-time data streams, calibration controls - Layout: Device-specific interfaces, data visualization, alarm displays - Data: Device protocols, real-time measurements, calibration parameters

Mapping to Polaris: - Form Section: Device parameters as Questionnaire items with data types - Canvas Section: Device interface screenshots with control overlays - File Attachment: Device protocols and calibration data - Text Section: Device instructions and measurement interpretations

Mapping from Polaris: - Questionnaire → Device Controls: Map items to device parameter settings - Canvas Overlays → Interface Elements: Reconstruct device control interfaces - Real-time Data → Dynamic Updates: Handle live data in static document format

5.2 Clinical Decision Support Forms¶

Architecture: Forms with embedded clinical algorithms and decision trees - Components: Clinical calculators, risk assessments, guideline algorithms - Layout: Decision tree visualizations, risk meters, recommendation displays - Data: Clinical algorithms, decision matrices, evidence references

Mapping to Polaris: - Form Section: Decision inputs as Questionnaire with calculation logic - Canvas Section: Decision tree diagrams and algorithm flowcharts
- Text Section: Clinical guidelines and evidence-based recommendations - File Attachment: Algorithm definitions and reference materials

Mapping from Polaris: - Questionnaire Logic → Algorithms: Reconstruct clinical calculations - Canvas Diagrams → Decision Trees: Recreate decision support visualizations - Text Guidelines → Help Systems: Provide contextual clinical guidance

5.3 Genomic/Laboratory Form Architectures¶

Architecture: Forms for complex laboratory data entry and genomic variant annotation - Components: Sequence browsers, variant browsers, lab result entry, pedigree editors - Layout: Scientific visualizations, data tables, hierarchical displays - Data: Genomic coordinates, variant annotations, pedigree relationships, lab values

Mapping to Polaris: - Canvas Section: Genomic browser screenshots with variant annotations - Form Section: Lab values and variant data as structured Questionnaire - File Attachment: Genomic data files (VCF, FASTA) with metadata - Text Section: Genomic interpretations and lab result narratives

Mapping from Polaris: - Canvas Annotations → Genomic Coordinates: Map to genome browser positions - Form Data → Lab Systems: Export to laboratory information systems - Embedded Sections → Multi-scale Data: Handle genomic data hierarchies

6. Emerging Form Architectures¶

6.1 AI-Assisted Form Architectures¶

Architecture: Forms with AI-powered auto-completion, validation, and suggestions - Components: NLP processors, machine learning models, predictive text, smart validation - Layout: AI suggestion overlays, confidence indicators, learning interfaces - Data: Training data, model predictions, confidence scores, user feedback

Mapping to Polaris: - Form Section: AI suggestions as pre-populated Questionnaire answers - Text Section: AI-generated narrative with confidence annotations - File Attachment: AI model definitions and training data references - Canvas Section: AI decision visualizations and confidence heatmaps

Mapping from Polaris: - Questionnaire → AI Training: Use responses to improve AI models - Text Narrative → NLP Processing: Extract structured data for AI training - Embedded Sections → Multi-modal AI: Train on complex nested data structures

6.2 Blockchain-Based Form Architectures¶

Architecture: Forms with cryptographic integrity and distributed validation - Components: Digital signatures, smart contracts, distributed ledgers, proof systems - Layout: Cryptographic verification displays, audit trails, consensus indicators - Data: Hash chains, digital signatures, consensus proofs, audit logs

Mapping to Polaris: - Form Section: Cryptographic metadata as Questionnaire items - File Attachment: Blockchain transaction records and proof chains - Text Section: Audit narratives and verification instructions - Bundle Signatures: Cryptographic integrity for entire document

Mapping from Polaris: - Bundle → Blockchain Transaction: Submit entire document to distributed ledger - Questionnaire Signatures → Smart Contracts: Execute form logic on blockchain - Embedded Sections → Merkle Trees: Create cryptographic proofs of nested content

7. Universal Mapping Principles¶

7.1 Bidirectional Transformation Rules¶

Structure Preservation: Maintain logical form structure through sections
Data Fidelity: Preserve all data values with appropriate type conversion
Layout Information: Capture positioning through Canvas sections when critical
Behavioral Logic: Represent form logic through Questionnaire skip patterns
Metadata Preservation: Store original format metadata in File Attachments
Fallback Strategies: Always provide Text section fallbacks for complex content

7.2 Complexity Handling Strategies¶

Recursive Decomposition: Break complex forms into nested embedded sections
Multi-section Mapping: Use multiple Polaris sections for complex layouts
Progressive Enhancement: Start with basic mapping, add complexity as needed
Format Negotiation: Allow systems to request specific levels of complexity
Graceful Degradation: Ensure basic functionality even with feature loss

7.3 Implementation Priorities¶

Common Architectures First: Focus on web forms, PDFs, and document-based forms
Standards Compliance: Ensure LOINC coding and FHIR conformance
Tool Integration: Provide conversion utilities for major form platforms
Validation Testing: Test round-trip conversion with major form systems
Community Feedback: Iterate based on real-world implementation experience

This comprehensive mapping strategy ensures the Polaris clinical document architecture can serve as a true universal translation target for any clinical form system, regardless of its underlying technology or architectural approach.

Recursive Containment Examples and Demonstrations¶

This section provides concrete examples demonstrating how the Polaris architecture achieves complete symmetric recursive containment, where any section type can embed any other section type at unlimited depth.

Example 1: Canvas with Embedded Questionnaire Components¶

Scenario: Cardiac Assessment with Interactive EKG¶

A cardiologist needs to annotate an EKG trace with assessment questions and patient drawings.

{
  "resourceType": "Bundle",
  "type": "document",
  "entry": [
    {
      "resource": {
        "resourceType": "Composition",
        "section": [
          {
            "code": {
              "coding": [{"system": "http://loinc.org", "code": "11540-0", "display": "Image"}]
            },
            "entry": [{"reference": "DocumentReference/ekg-canvas"}]
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "DocumentReference",
        "id": "ekg-canvas",
        "content": [{
          "attachment": {
            "contentType": "image/png",
            "data": "[base64 EKG trace image]"
          }
        }],
        "extension": [
          {
            "url": "https://fhir.apps.health/StructureDefinition/polaris-canvas-annotation",
            "extension": [
              {
                "url": "annotationType",
                "valueCode": "embedded-form-section"
              },
              {
                "url": "coordinates", 
                "valueString": "{\"x\": 200, \"y\": 100, \"width\": 300, \"height\": 200}"
              },
              {
                "url": "embeddedSection",
                "valueSection": {
                  "code": {
                    "coding": [{"system": "http://loinc.org", "code": "74468-0"}]
                  },
                  "entry": [{"reference": "Questionnaire/rhythm-assessment"}]
                }
              }
            ]
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Questionnaire",
        "id": "rhythm-assessment", 
        "item": [
          {
            "linkId": "rhythm",
            "text": "What rhythm do you see?",
            "type": "choice",
            "answerOption": [
              {"valueString": "Normal sinus rhythm"},
              {"valueString": "Atrial fibrillation"}
            ]
          },
          {
            "linkId": "patient-drawing",
            "text": "Patient's description of symptoms",
            "type": "embedded-section",
            "extension": [
              {
                "url": "https://fhir.apps.health/StructureDefinition/polaris-embedded-section-answer",
                "valueSection": {
                  "code": {"coding": [{"system": "http://loinc.org", "code": "11540-0"}]},
                  "entry": [{"reference": "DocumentReference/patient-chest-drawing"}]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Result: EKG image with a questionnaire overlay at coordinates (200,100), where one question's answer is itself a canvas containing the patient's drawing of their chest pain location.

Example 2: Text Section with Embedded Canvas with Embedded Forms¶

Scenario: Surgical Report with Anatomical Diagrams and Assessment Forms¶

// Text section with embedded content
* section[textSection].text.div = """
<div>
  <h2>Surgical Procedure Report</h2>
  <p>Patient underwent laparoscopic cholecystectomy. The following anatomical 
     diagram shows the surgical approach:</p>

  <div data-fhir-embedded="canvas-section" 
       data-section-ref="DocumentReference/surgical-diagram">
    [Embedded surgical diagram with positioned assessment forms]
  </div>

  <p>Post-operative assessment completed with patient input at marked locations.</p>
</div>
"""

// The embedded canvas contains positioned forms
DocumentReference: surgical-diagram
  content.attachment.data = "[base64 anatomical diagram]"
  extension[annotations] = [
    {
      annotationType: "embedded-form-section",
      coordinates: "{\"x\": 150, \"y\": 200}",
      embeddedSection: {
        // Pain assessment questionnaire positioned over surgical site
        entry: ["Questionnaire/post-op-pain-assessment"]
      }
    },
    {
      annotationType: "embedded-form-section", 
      coordinates: "{\"x\": 300, \"y\": 150}",
      embeddedSection: {
        // Recovery tracking form positioned over recovery area
        entry: ["Questionnaire/recovery-tracking"]
      }
    }
  ]

Result: Surgical report text that contains an embedded anatomical diagram, which itself contains multiple questionnaires positioned at specific anatomical locations.

Example 3: Infinite Recursive Nesting¶

Document Structure:
└── Text Section: "Comprehensive Neurological Assessment"
    ├── Embedded Canvas: Brain MRI scan
    │   ├── Annotation at (100,150): Lesion marker
    │   └── Embedded Form at (200,100): Lesion Assessment
    │       ├── Question: "Lesion characteristics?"
    │       ├── Answer: Embedded Text: "Detailed radiological description..."
    │       │   └── Embedded Canvas: Magnified view of lesion
    │       │       └── Embedded Form: Measurement tool
    │       │           └── Answer: Embedded Canvas: Measurement annotations
    │       └── Question: "Clinical correlation?"
    │           └── Answer: Embedded Text: "Patient symptoms include..."
    │               └── Embedded Form: Symptom severity scale
    │                   └── Answer: Embedded Canvas: Patient pain drawing
    ├── Text continues: "Cognitive assessment results..."
    └── Embedded Form: Montreal Cognitive Assessment (MoCA)
        ├── Question: "Clock drawing test"
        │   └── Answer: Embedded Canvas: Patient's clock drawing
        │       ├── Scoring annotations at various coordinates
        │       └── Embedded Form: Scoring rubric
        └── Question: "Additional observations"
            └── Answer: Embedded Text: "Patient exhibited..."

Example 4: Real-World Clinical Form Architectures Mapped to Polaris¶

PDF Form with Interactive Elements → Polaris Mapping¶

Original PDF Form: - Page 1: Patient demographics form - Page 2: Medical history with checkboxes and signature area - Interactive JavaScript calculating BMI

Polaris Representation:

// Canvas section for PDF page as background
* section[canvasSection].entry = "DocumentReference/demographics-pdf-page1"
  extension[annotations] = [
    // Name field overlay
    {
      annotationType: "embedded-form-section",
      coordinates: "{\"x\": 100, \"y\": 50, \"width\": 200, \"height\": 25}",
      embeddedSection: {
        entry: ["Questionnaire/name-field"]
      }
    },
    // BMI calculator overlay  
    {
      annotationType: "embedded-form-section",
      coordinates: "{\"x\": 300, \"y\": 200, \"width\": 150, \"height\": 100}",
      embeddedSection: {
        entry: ["Questionnaire/bmi-calculator"]
      }
    }
  ]

// The BMI calculator questionnaire can embed results as text
Questionnaire: bmi-calculator
  item[calculation-result].extension[embeddedSectionAnswer] = {
    valueSection: {
      // Embedded text section with calculated BMI result
      text.div: "<div>Calculated BMI: <strong>24.5</strong></div>"
    }
  }

Example 5: 3D/VR Form → Polaris Mapping¶

Original VR Form: - 3D anatomical model - Spatial questionnaires at organ locations - Gesture-based annotations

Polaris Representation:

// Canvas section for 3D model screenshot/render
* section[canvasSection].entry = "DocumentReference/3d-anatomy-render"
  extension[annotations] = [
    // Heart assessment at 3D coordinates (converted to 2D)
    {
      annotationType: "embedded-form-section",
      coordinates: "{\"x\": 250, \"y\": 180, \"z\": 150}",  // 3D → 2D projection
      embeddedSection: {
        entry: ["Questionnaire/heart-assessment"]
      }
    }
  ]

// Heart assessment can embed gesture data as canvas
Questionnaire: heart-assessment  
  item[gesture-annotation].extension[embeddedSectionAnswer] = {
    valueSection: {
      entry: ["DocumentReference/gesture-trace"]  // Canvas with gesture path
    }
  }

Example 6: AI-Assisted Form → Polaris Mapping¶

Original AI Form: - Text input with AI suggestions - Confidence indicators - Dynamic form generation based on AI analysis

Polaris Representation:

// Form section with AI-suggested content
* section[formSection].entry = "QuestionnaireResponse/ai-assisted-assessment"

QuestionnaireResponse: ai-assisted-assessment
  item[chief-complaint].answer.extension[embeddedSectionAnswer] = {
    valueSection: {
      // AI suggestion embedded as text section
      text.div: """
        <div class="ai-suggestion" data-confidence="0.85">
          <p>AI suggests possible diagnosis: Acute appendicitis</p>
          <div data-fhir-embedded="canvas-section" data-section-ref="ai-heatmap">
            [Confidence heatmap visualization]
          </div>
        </div>
      """
    }
  }

Symmetry Matrix: All Possible Embeddings¶

Container	Can Embed	Mechanism
Text → Text	PolarisEmbeddedSectionExtension	Nested narratives, citations
Text → Form	PolarisEmbeddedSectionExtension	Inline questionnaires, assessments
Text → Canvas	PolarisEmbeddedSectionExtension	Inline images, diagrams
Text → File	PolarisEmbeddedSectionExtension	Referenced documents, attachments
Form → Text	PolarisEmbeddedSectionResponseExtension	Narrative answers, explanations
Form → Form	PolarisEmbeddedSectionResponseExtension	Sub-questionnaires, conditional logic
Form → Canvas	PolarisEmbeddedSectionResponseExtension	Drawing answers, image selections
Form → File	PolarisEmbeddedSectionResponseExtension	Document uploads, file attachments
Canvas → Text	PolarisCanvasAnnotationExtension	Positioned text annotations
Canvas → Form	PolarisCanvasAnnotationExtension	Positioned questionnaires, hotspots
Canvas → Canvas	PolarisCanvasAnnotationExtension	Nested images, zoom regions
Canvas → File	PolarisCanvasAnnotationExtension	Positioned file references
File → Text	PolarisFileMetadataExtension	Document structure metadata
File → Form	PolarisFileMetadataExtension	Embedded form definitions
File → Canvas	PolarisFileMetadataExtension	Image/diagram metadata
File → File	PolarisFileMetadataExtension	Archive contents, nested files

Implementation Guidelines for Recursive Containment¶

1. Bundle Integrity Rules¶

All embedded sections MUST be complete and self-contained
No external references allowed in embedded content
Embedded sections inherit parent section's context

2. Depth Limitation Recommendations¶

// Recommended maximum nesting depth for performance
* section.extension[embeddedSection].extension[maxDepth].valueInteger = 10

// Circular reference prevention
* section.extension[embeddedSection].extension[preventCircular].valueBoolean = true

3. Fallback Strategies for Complex Nesting¶

// Always provide text fallback for deeply nested content
* extension[fallbackText].valueString = "Complex interactive assessment form with anatomical diagrams and measurement tools"

// Progressive disclosure hints
* extension[displayHint].valueString = "expand-on-interaction"

4. Performance Considerations¶

Lazy Loading: Embedded sections can be loaded on-demand
Compression: Deep nesting may benefit from content compression
Caching: Commonly embedded sections should be cached
Validation: Complex nesting requires enhanced validation rules

This recursive containment architecture enables the Polaris clinical document format to represent arbitrarily complex clinical forms and assessments while maintaining FHIR compliance and ensuring graceful degradation across different systems.

Recursive Containment Strategy¶

Embedded Section Patterns¶

Rather than simple cross-referencing, the Polaris architecture supports complete symmetric recursive containment where any section type can embed any other section type as actual content:

Text Sections → Embedded Sections: Use data-fhir-embedded attributes in XHTML with PolarisEmbeddedSectionExtension to embed complete Form/Canvas/File sections inline
Form Sections → Embedded Sections: Questionnaire field values can contain complete Canvas/Text/File sections as the actual answer content via PolarisEmbeddedSectionResponseExtension
Canvas Sections → Embedded Sections: Canvas annotations can embed complete Form/Text/File sections at specific X,Y coordinates via PolarisCanvasAnnotationExtension
File Sections → Embedded Sections: File attachments can contain embedded sections as metadata describing structured content within files via PolarisFileMetadataExtension
Complete Symmetry: Every section type can embed every other section type, including itself (recursive nesting)
Unlimited Depth: Any embedded section can itself contain embedded sections, creating unlimited recursive depth

Bundle Integrity Rules¶

All referenced resources MUST be included in the Bundle
No external references allowed (ensures portability)
Version consistency between Questionnaire and QuestionnaireResponse
Canonical URL resolution within Bundle scope

Interoperability and Fallback Strategies¶

Translation Capabilities¶

Source System Capability	Polaris Representation	Target System Fallback
Rich text with embedded forms	Text section with embedded element extensions	Plain text with form data as appendix
Dynamic forms	Questionnaire + QuestionnaireResponse	Read-only name-value pairs
PDF with annotations	Canvas section with annotation overlays	Static PDF attachment
Drawings/signatures	Canvas annotations with coordinate data	Flattened image
Arbitrary file attachments	File attachment sections with metadata	Basic document attachment
Multi-section documents	Multiple sections of each type in any order	Sequential sections with type indicators

Graceful Degradation Rules¶

Text sections: Always preserve as XHTML narrative
Form sections: Convert to read-only text representation if Questionnaire not supported
Canvas sections: Fall back to static image/PDF if annotations not supported
File attachment sections: Preserve as basic DocumentReference with MIME type
Cross-references: Maintain as textual descriptions if dynamic linking unavailable
Section ordering: Maintain logical flow even if specific section types not supported

Validation and Quality Assurance¶

FHIR Validation Rules¶

Bundle integrity: All references resolved within bundle
Profile conformance: All resources conform to Polaris profiles
Clinical constraints: Business rules for document lifecycle
Security requirements: Proper confidentiality and provenance

Testing Strategy¶

Profile validation using FHIR IG Publisher
Round-trip testing: Polaris → Target EMR → Polaris
Degradation testing: Feature removal and reconstruction
Cross-system interoperability testing

Future Considerations¶

FHIR R5 Migration Path¶

Leverage improved Composition features in R5
Enhanced Bundle capabilities
Better questionnaire rendering support

Canadian Standards Evolution¶

Monitor CA-Core+ composition module development
Align with provincial implementation guide updates
Integrate with Canadian terminology updates

Technology Enhancement¶

Web Components for embedded elements
SMART on FHIR integration for dynamic forms
Digital signature integration with Provenance

Conclusion¶

This design provides a comprehensive, standards-based approach to clinical document representation that meets the user's requirements for universal EMR interoperability while maintaining graceful degradation capabilities. The four-section architecture with recursive containment offers the flexibility needed to represent diverse clinical content while ensuring consistent, predictable behavior across different EMR systems.

Key Enhancements in Version 2.0:¶

Standard LOINC Codes: Text sections use LOINC 34109-9 "Note", Canvas sections use LOINC 11540-0 "Image", Form sections use LOINC 74468-0/74465-6 for full standards compliance
Flexible Section Architecture: Multiple sections of each type allowed in any order, supporting complex document structures
File Attachment Support: Arbitrary file types supported with comprehensive metadata and fallback strategies
Recursive Containment: Any section type can embed any other section type as actual content (not just references)
Universal Form Architecture Mapping: Comprehensive strategies for mapping to/from every conceivable clinical form system
Enhanced Questionnaire Embedding: Form field values can contain complete Canvas/Text/File sections
Enhanced Interoperability: Better alignment with PS-CA, MERT, and CA-Core+ requirements

The FHIR profiles specified in this document provide a solid foundation for implementation, with clear migration paths for future enhancements and strong alignment with Canadian healthcare standards. The design successfully balances innovation with standards compliance, ensuring broad adoption potential across Canadian healthcare systems.

Polaris Clinical Document Architecture - Design Document¶

Executive Summary¶

Key Design Principles¶

Architecture Overview¶

Core Resource Model¶

Section Type Architecture¶

Detailed FHIR Profile Specifications¶

1. PolarisCoreDocumentBundle Profile¶

Key Constraints:¶

Bundle Entry Requirements:¶

2. PolarisCoreComposition Profile¶

Core Elements:¶

Section Structure:¶

3. Text Section Extensions¶

PolarisMarkdownExtension¶

PolarisEmbeddedSectionExtension¶

4. Form Section Profiles¶

PolarisQuestionnaire Profile¶

Key Constraints:¶

PolarisQuestionnaireResponse Profile¶

Key Features:¶

5. Canvas Section Profiles¶

PolarisCanvasDocumentReference Profile¶

Enhanced Features:¶

PolarisCanvasMetadataExtension¶

PolarisCanvasAnnotationExtension¶

6. File Attachment Section Profiles¶

PolarisFileAttachmentDocumentReference Profile¶

Key Features:¶

PolarisFileMetadataExtension¶

Clinical Form Library Architectures and Mapping Strategies¶

1. Static Layout Form Architectures¶

1.1 Native Mobile/Desktop App Forms¶

1.2 Web Form Libraries (React, Angular, Vue Components)¶

2. Document-Based Form Architectures¶

2.1 Text Document Forms (Word, Google Docs)¶

2.2 PDF Form Architectures¶

2.3 Scanned Paper Form Architectures¶

3. Custom Form Engine Architectures¶

3.1 Absolute Positioning Form Engines¶

3.2 Dynamic Layout Form Engines¶

3.3 Flow-Based Form Architectures¶

4. Multimedia Form Architectures¶

4.1 Video/Audio Form Architectures¶

4.2 3D/VR Form Architectures¶

5. Specialized Clinical Form Architectures¶

5.1 Medical Device Integration Forms¶

5.2 Clinical Decision Support Forms¶

5.3 Genomic/Laboratory Form Architectures¶

6. Emerging Form Architectures¶

6.1 AI-Assisted Form Architectures¶

6.2 Blockchain-Based Form Architectures¶

7. Universal Mapping Principles¶

7.1 Bidirectional Transformation Rules¶

7.2 Complexity Handling Strategies¶

7.3 Implementation Priorities¶

Recursive Containment Examples and Demonstrations¶

Example 1: Canvas with Embedded Questionnaire Components¶

Scenario: Cardiac Assessment with Interactive EKG¶

Example 2: Text Section with Embedded Canvas with Embedded Forms¶

Scenario: Surgical Report with Anatomical Diagrams and Assessment Forms¶

Example 3: Infinite Recursive Nesting¶

Scenario: Complex Multi-Modal Clinical Assessment¶

Example 4: Real-World Clinical Form Architectures Mapped to Polaris¶

PDF Form with Interactive Elements → Polaris Mapping¶

Example 5: 3D/VR Form → Polaris Mapping¶

Example 6: AI-Assisted Form → Polaris Mapping¶

Symmetry Matrix: All Possible Embeddings¶

Implementation Guidelines for Recursive Containment¶

1. Bundle Integrity Rules¶

2. Depth Limitation Recommendations¶

3. Fallback Strategies for Complex Nesting¶

4. Performance Considerations¶

Recursive Containment Strategy¶

Embedded Section Patterns¶

Bundle Integrity Rules¶

Interoperability and Fallback Strategies¶

Translation Capabilities¶

Graceful Degradation Rules¶

Validation and Quality Assurance¶