Document Service — Service Overview
Status: populated
Owner: TBD
Last updated: 2026-04-18
Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The document-service provides enterprise clinical document management for the Ghasi eHealth platform. It owns the full lifecycle of clinical documents: template authoring, server-side PDF generation from FHIR-bound data, upload and virus-scanning of scanned paper records, versioned artifact storage in S3-compatible object storage, and audited retrieval with signed URLs.
It is the canonical owner of FHIR DocumentReference, Binary, and Provenance resources for generated and uploaded documents.
2. Bounded Context
| Aspect | Detail |
|---|
| DDD context | Clinical Documents |
| Module ID | PLAT-DMS |
| Service registry | 03-platform-services.md |
| Internal base URL | http://document-service:3020 |
| External URL (via Kong) | https://api.ghasi-health.af/v1/ |
| Package name | @ghasi/service-document |
3. Responsibilities
| Responsibility | Notes |
|---|
| Template library management | Draft → publish lifecycle; semantic versioning; tenant + facility scope |
| PDF generation (synchronous + async) | Server-side rendering with FHIR data binding; never client-side |
| Document upload and ingestion | Multipart upload; virus scan on every upload |
| Object storage management | S3-compatible (AWS S3 or MinIO on-prem); AES-256 encryption at rest |
| Signed URL generation | Temporary access URLs; short-lived |
| FHIR DocumentReference + Binary creation | Canonical FHIR metadata for every stored document |
| Artifact versioning and supersession | relatesTo + Provenance for clinical amendments |
| Platform reference form catalog | Curated first-class templates (e.g. General Test Requisition) |
| Audit events on every access | View, download, print, export; 7-year retention |
| Async render jobs | Pollable status; downloadable result on completion |
4. Non-Responsibilities
| Not owned here | Owned by |
|---|
| DICOM pixel data management | radiology-service / PACS |
| IHE XDS registry/repository | interop-service (adapter only) |
| Qualified electronic signatures (PKI) | Future licensed module |
| Vendor OCR processing | Optional integration behind interfaces |
| Narrative clinical notes (NLP-structured) | patient-chart-service |
| Imaging pixels | radiology-service |
| Template designer UI | ehr-web frontend (consumes this service's API) |
| FHIR gateway routing | interop-service |
5. Architecture Diagram
6. Referenced-By Services
| Consumer | Documents used |
|---|
| patient-chart-service | Clinical notes attachments, discharge summaries |
| interop-service | CDA/CCD documents for HIE exchange |
| patient-portal-service | Patient-visible documents |
| orders-service | Referral letters, lab requisitions |
7. FHIR Resource Ownership
| Resource | Role |
|---|
DocumentReference | Metadata for clinical and administrative documents; primary search surface |
Binary | PDF or image bytes stored in object storage; referenced from DocumentReference.content |
Provenance | Sign/amend and system-generated document activity |
Composition | Optional structured sections for long-form reports |
8. Licensing Gate
| License key | Capabilities |
|---|
ehr.documents | Base: view/list/generate from published templates, store artifacts, audit |
ehr.documents.designer | Template authoring, draft workflow, promote to published |
ehr.documents.bulk | High-volume async generation and admin bulk operations |
Unlicensed tenants receive HTTP 403 MODULE_NOT_LICENSED on gated endpoints. Deactivation preserves historical artifacts per retention policy.
9. Key Architectural Decisions
| Decision | Rationale |
|---|
| Object storage (S3/MinIO) for binary content | Scalable; tenant-scoped paths; supports presigned URLs; on-prem via MinIO |
| Server-side PDF rendering only | No PHI in client-side or third-party rendering; regulatory requirement |
| Virus scan on every upload | Malware prevention; quarantine quarantined uploads to DLQ event |
| FHIR-first metadata | DocumentReference + Binary for interoperability; HIE-compatible |
| Outbox pattern for events | Guarantees at-least-once delivery; no audit gap on crash |
| Signed URL with short TTL | Access control without exposing raw object storage paths |
| Tenant-scoped storage paths | /{tenantId}/{documentId}/ prefix on every object |
| Offline: view-only for cached PDFs | Server render required for generation; client queues render requests for replay |
10. Source Reconciliation
Single source module: services/document-service/_sources/document-management/. No multi-module merge required. Legacy module ID PLAT-DMS preserved in legacy FR references. Source referenced the broader spec as version 1.1 (2026-04-06). Platform reference forms catalog (REFERENCE_FORMS.md) is authoritative for platformFormKey values.