Document Service — Deployment Topology
Status: populated
Owner: TBD
Last updated: 2026-04-18
Companion: Service Template · 17 technology-stack
1. Runtime
| Property | Value |
|---|
| Runtime | Node.js 22 LTS |
| Framework | NestJS 11 |
| Language | TypeScript 5.x |
| Package | @ghasi/service-document |
| Port | 3020 |
| Container base | node:22-alpine |
2. Replicas and Scaling
| Environment | Min replicas | Max replicas | Scaling trigger |
|---|
| Production (API + render workers) | 2 API + 2 workers | 8 API + 10 workers | CPU > 60 % or render job queue > 100 |
| Staging | 1 API + 1 worker | 3 API + 3 workers | — |
| Dev/local | 1 combined | 1 | — |
API instances (request handling) and render workers (async PDF generation) are separate deployment units that share the same codebase but start with different profiles.
3. Infrastructure Dependencies
| Dependency | Type | Notes |
|---|
| PostgreSQL 16 | Primary store | Schema document_svc; RLS enforced |
| Object Storage (S3 / MinIO) | Binary storage | Tenant-scoped paths; AES-256 at rest |
| ClamAV | Virus scanner | Sidecar container or dedicated service |
| NATS JetStream | Message bus | Streams: doc-template-events, doc-render-events, doc-artifact-events, doc-security-events |
| interop-service / FHIR gateway | HTTP | FHIR binding resolution + DocumentReference creation |
| config-service | HTTP | Tenant branding tokens for PDF rendering |
| Kong | API Gateway | Routes /v1/document* with JWT auth |
| Keycloak | Identity | JWT issuer |
| OpenTelemetry Collector | Telemetry | OTLP → Grafana / Tempo |
4. Object Storage Configuration
| Deployment type | Object storage | Encryption |
|---|
| Cloud (AWS) | Amazon S3 | SSE-KMS per-tenant key |
| On-premises | MinIO | SSE with platform-managed key |
| Development | MinIO (docker compose) | Default MinIO encryption |
Bucket naming: ghasi-documents-{region}-{env} (cloud) or documents (on-prem MinIO).
5. ClamAV Integration
ClamAV runs as a sidecar container (clamav:latest) or as a dedicated service. The document-service calls ClamAV via the clamd TCP protocol (port 3310). Virus definition updates are scheduled daily.
6. Regions
| Region | Role | Notes |
|---|
| Primary (Afghanistan MoPH) | Active | All write traffic; primary DB; primary object storage |
| Secondary (DR) | Standby | DB read replica; object storage replication; NATS replication |
Clinical documents are subject to Afghanistan MoPH data residency requirements. No document data leaves the designated region without explicit tenant policy.
7. Health Checks
| Endpoint | Checks |
|---|
GET /health/live | Process alive |
GET /health/ready | PostgreSQL OK; object storage reachable; ClamAV connected; NATS connected |
8. Resource Limits (Production)
| Pod | CPU Request | CPU Limit | Memory Request | Memory Limit |
|---|
| API pod | 250 m | 1000 m | 256 Mi | 512 Mi |
| Render worker | 500 m | 2000 m | 512 Mi | 1 Gi |
Render workers are memory-intensive due to PDF generation (Puppeteer/PDFLib). Workers auto-scale independently of API pods.
9. Deployment Diagram