Document Service

Stores, renders, and serves policy documents, EOBs, lab results, and other member-facing documents.

Overview

The Document Service provides centralised document management for the platform. It owns two concerns: document templates (reusable layouts for policy welcome letters, invoices, EOBs, etc.) and rendered document instances (the actual PDFs produced from a template + data and stored for retrieval).

Documents are generated by consuming Kafka events from other services — for example, when a claim is adjudicated, the Claims event triggers a document generation job that renders an EOB PDF using the appropriate template. Generated documents are stored in the database and served as PDF responses via the retrieval API.

The service uses an outbox pattern to reliably publish document.generated events after a document is created, allowing other services (Notifications, Member Portal) to link to or reference the new document.

Responsibilities

• Manage document templates (CRUD) for all document types
• Generate rendered document instances from events and direct API calls
• Store rendered document content (PDF bytes) linked to a locator
• Serve document retrieval for member portal and other consumers
• Publish document.generated events for downstream notification

Database

Schema: document_service

Table	Purpose
templates	Document template definitions (type, content, version)
documents	Rendered document instances with content, locator, and metadata
outbox	Transactional outbox for document.generated event publishing

API Routes

Method	Path	Auth	Description
GET	/documents/{locator}	JWT	Retrieve a rendered document as PDF

Events

Publishes

Topic	When
document.generated	A new document is successfully rendered and stored

Consumes

Topic	Action taken
claims.adjudicated	Renders an EOB document for the adjudicated claim
enrollment.policy.activated	Renders a policy welcome letter and schedule of benefits
billing.invoice.generated	Renders a PDF invoice for the billing period

Dependencies

The Document Service has no runtime HTTP dependencies on other services. All triggers arrive via Kafka.

Key Design Decisions

Event-driven generation: Documents are generated reactively from domain events rather than on-demand. This decouples the rendering workload from request latency — the member portal fetches an already-rendered PDF, not one generated in real time.

Content stored in database: Document content (PDF bytes) is stored directly in the documents table for simplicity at current scale. The outbox ensures a document.generated event is published atomically with the database insert, so downstream services are notified reliably even if the process restarts mid-publish.