Document Service — Domain Model
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Aggregates
1.1 DocumentTemplate
The authoritative definition of a document structure. Versioned; published versions are immutable.
| Field | Type | Notes |
|---|---|---|
id | TemplateId (prefix tmpl_) | — |
tenantId | TenantId | — |
name | string | Human-readable unique name per tenant |
category | DocumentCategory | e.g. prescription, lab_requisition, report, letter, consent |
facilityId | FacilityId | null | Optional facility scope |
status | TemplateStatus | draft | published | retired |
currentVersionId | TemplateVersionId | null | Points to the active published version |
origin | platform | tenant | platform = owned by product; tenant = authored by tenant |
platformFormKey | string | null | Stable reference form key when origin=platform or forked |
forkedFromPlatformFormKey | string | null | Set when tenant forks a platform reference template |
createdBy | UserId | — |
updatedAt | Timestamp | — |
State machine:
Invariants:
- A published template version is immutable; changes require a new version.
- Platform reference templates (
origin=platform) cannot be edited or republished by tenant users; only forked. effectiveToin the past: generation requests against that version are rejected unless policy explicitly allows reprint.
1.2 DocumentTemplateVersion
An immutable snapshot of a template's definition at a point in time.
| Field | Type | Notes |
|---|---|---|
id | TemplateVersionId (prefix tv_) | — |
templateId | TemplateId | — |
tenantId | TenantId | — |
semver | string | e.g. 1.2.0 |
definition | JSONB | Layout, sections, field bindings |
effectiveFrom | Date | — |
effectiveTo | Date | null | — |
publishedAt | Timestamp | null | Set on publish transition |
checksum | string | SHA-256 of the definition JSON |
platformPackageVersion | string | null | Reference package semver when origin=platform |
1.3 DocumentRenderJob
Tracks an asynchronous PDF generation request.
| Field | Type | Notes |
|---|---|---|
id | RenderJobId (prefix rjob_) | — |
tenantId | TenantId | — |
templateVersionId | TemplateVersionId | — |
patientId | PatientId | — |
encounterId | EncounterId | null | — |
context | JSONB | { resourceType, id } for FHIR context resource |
status | RenderJobStatus | queued | running | completed | failed |
inputSnapshotHash | string | SHA-256 of resolved input data; enables regeneration audit |
binaryId | string | null | FHIR Binary logical ID when completed |
documentReferenceId | string | null | FHIR DocumentReference ID when completed |
errorCode | string | null | Stable error code on failure |
clientMutationId | string | null | Idempotency key for offline replay |
createdAt | Timestamp | — |
completedAt | Timestamp | null | — |
State machine:
1.4 DocumentArtifact (logical)
Maps to FHIR DocumentReference + Binary + optional Provenance. No separate Postgres table — the FHIR resources are the system of record.
| Logical field | FHIR mapping |
|---|---|
| Document ID | DocumentReference.id |
| Binary content | Binary.data (stored in object storage; reference in DocumentReference.content.attachment.url) |
| Patient | DocumentReference.subject |
| Encounter | DocumentReference.context.encounter |
| Document type | DocumentReference.type (LOINC code) |
| Category | DocumentReference.category |
| Author | DocumentReference.author |
| Status | DocumentReference.status |
| Related (supersession) | DocumentReference.relatesTo |
| Provenance | Provenance.target → DocumentReference |
| Origin | DocumentReference.extension[origin] |
1.5 AccessGrant (logical)
Represents a temporary access grant for a document (presigned URL or portal share). Not persisted as a separate table; generated on demand with short TTL and recorded in audit.
2. Value Objects
| Value Object | Type |
|---|---|
TemplateId | Branded ULID, prefix tmpl_ |
TemplateVersionId | Branded ULID, prefix tv_ |
RenderJobId | Branded ULID, prefix rjob_ |
TemplateStatus | draft | published | retired |
DocumentCategory | prescription | lab_requisition | report | letter | consent | discharge_summary | referral | scanned_record | other |
RenderJobStatus | queued | running | completed | failed |
DocumentOrigin | platform | tenant |
PlatformFormKey | Stable string, e.g. platform.dms.general-lab.general-test-requisition |
3. Domain Events
| Event subject (NATS) | Trigger | Retention |
|---|---|---|
document.template.created.v1 | Template metadata created | 7 years |
document.template.updated.v1 | Template metadata updated | 7 years |
document.template.version_published.v1 | Template version published | 7 years |
document.template.retired.v1 | Template retired | 7 years |
document.render.started.v1 | Async render job started | 30 days |
document.render.completed.v1 | Render job completed successfully | 30 days |
document.render.failed.v1 | Render job failed | 30 days |
document.artifact.registered.v1 | DocumentReference created (generated or uploaded) | 7 years |
document.upload.quarantined.v1 | Upload failed virus scan | 7 years |
4. Ubiquitous Language
| Term | Definition |
|---|---|
| Template | A versioned document structure with layout and FHIR data bindings |
| Template Version | An immutable snapshot of a template's definition at a specific semver |
| Published Version | An immutable, active template version available for generation |
| Platform Reference Form | A first-class template shipped with the platform; has a stable platformFormKey; immutable by tenants |
| Tenant Fork | A tenant-owned copy of a platform reference template; has a new templateId but lineage to the source platformFormKey |
| Render Job | An asynchronous PDF generation task tracked by status |
| Artifact | The generated or uploaded PDF document; represented as FHIR DocumentReference + Binary |
| Supersession | When a corrected artifact replaces an older one, preserving the original with a relatesTo link |
| Input Snapshot Hash | SHA-256 of resolved FHIR binding data; enables audit of what data produced which PDF |
| Signed URL | A short-lived presigned URL granting temporary read access to a stored object |
| Virus Quarantine | An uploaded file flagged by the virus scanner; stored separately; access blocked pending review |