Document author: Mark Evans
Document version: 1.0
Status: Draft
Approved by: ...
Date approved: ...
Review date: 2026/10/22
Template version: 1.2
| Date | Version | Author | Revision Summary |
|---|---|---|---|
| 2025-10-22 | v1.0 | Mark Evans | Initial draft |
This document describes the architecture for the GP Practice Document Submission API — a service that accepts FHIR R4 Bundles (type=transaction) containing clinical documents (DocumentReference + Binary + Patient + Encounter + Practitioner + Organisation) and delivers them to GP practice systems.
- Accept FHIR R4 Bundles (transaction)
- Validate syntactic and semantic correctness of FHIR resources
- Ensure the associated Binary resource is stored reliably
- Authenticate and authorize senders (API Gateway)
- Provide clear OperationOutcome responses for success/failure
- Security: Confidentiality, integrity and availability of PHI
- Performance: Typical bundle processing in <2s for validation path (non-blocking storage)
- Scalability: Horizontal scaling on stateless API containers
- Observability: Tracing, metrics and structured logging for each submission
| Role/Name | Contact | Expectations |
|---|---|---|
| GP Practices | Receive validated clinical documents reliably | |
| Hospital EHRs | Ability to submit discharge summaries | |
| Platform Operators | Secure, observable and resilient service |
- Must accept FHIR R4 (JSON) Bundles as input.
- Must run in a typical cloud environment (managed Kubernetes or PaaS).
- Must store binary clinical documents in an object store (S3-compatible).
- Must integrate with existing identity provider (jwt).
The system boundary is the GP Practice Document Submission API. It receives FHIR Bundles from external senders (Hospital systems), validates them, persists metadata, stores binary files in object storage, and forwards or makes available the clinical documents to the GP Practice System.
- Replace ad-hoc file transfer with a validated, auditable API for clinical document submission.
- Provide consistent OperationOutcome responses aligned with NHS FHIR practices.
- External senders: Hospital EHRs, middleware
- API Gateway: TLS termination, authentication, rate-limiting
- GP Docs API: Spring Boot application (controller + services)
- Backend: Postgres for metadata, object store for Binary resources
- Use a layered Spring Boot application with Controller -> Service -> Repository pattern.
- Use HAPI FHIR libraries for parsing and validating FHIR R4 resources (enabled in FhirConfig.java).
- Keep API stateless so it can scale horizontally; persist state to Postgres and object store.
- Push logs and metrics to central observability stack (Prometheus/Grafana + ELK)
Important runtime scenarios are captured as sequence diagrams below.
Generic cloud deployment:
- API Gateway (managed) — TLS termination and OAuth2/OIDC authentication.
- Kubernetes cluster (or container service) running stateless GP Docs API pods behind an autoscaling group.
- Postgres (managed) for metadata and audit records.
- Object storage for Binary resources.
- Optional message broker (e.g., SNS/SQS or Kafka) for async delivery to GP systems.
- Observability stack: Prometheus, Grafana, ELK/Cloud Logging.
- Layered architecture (Controller -> Service -> Repository)
- Validation-as-a-service (FhirValidationService)
- Transport: TLS 1.2+ enforced at API Gateway.
- Authentication/Authorization: OAuth2/OIDC; clients obtain tokens; scopes limit access.
- Input validation: strict FHIR validation and size limits for Binary resources.
- Data protection: store PHI encrypted at rest (DB and object store) and encrypted in transit.
- Audit: immutable audit trail for submissions (write-ahead logs/audit table).
- Secrets: use cloud secret manager for DB credentials and encryption keys.
- Stateless API nodes behind load balancer enable horizontal scaling.
- Postgres scaled vertically or via read replicas for read-heavy workloads.
- Object store offloads large binary sizes and scales independently.
- Retries with exponential backoff for transient errors (e.g., storage timeouts).
- Circuit breakers on downstream calls if integrated with external GP endpoints.
- Dead-letter queue for failed async deliveries.
- Structured logging (JSON) with correlation IDs per submission.
- Metrics: request rate, validation success/failure, processing latency.
- Tracing (W3C TraceContext) to follow submission across services.
- Treat submitted data as sensitive health data; follow regional regulations (e.g., UK Data Protection Act / GDPR).
- Data retention policies for audit logs and binaries must be defined.
- Use HAPI FHIR for validation and parsing (as implemented in FhirConfig.java).
- Keep API stateless; use cloud-managed DB and object storage.
| ID | Impact |
|---|---|
| ADR-001 | Use HAPI FHIR for validation and resource handling |
- Availability: 99.9% SLA for core submission paths.
- Latency: median validation latency < 2s.
- Throughput: scale to handle bursts of submissions from multiple hospital sources.
| ID | Impact | Mitigation / Plan | Owner |
|---|---|---|---|
| R-001 | High | Sensitive PHI exposure if TLS/auth misconfigured | Platform Ops |
| R-002 | Medium | Malformed FHIR bundles cause processing errors | Improve validation & clearer OperationOutcome messages |
| ID | Impact | Mitigation / Plan | Owner |
|---|---|---|---|
| TD-001 | Medium | No async delivery pipeline implemented | Introduce message broker for retries and durability |
| Term | Definition |
|---|---|
| FHIR | Fast Healthcare Interoperability Resources (R4) |
| Bundle | FHIR Bundle resource (transaction) |
| DocumentReference | FHIR resource pointing to clinical document |
| Binary | FHIR resource containing binary payload (PDF) |