Needs Analysis: Implement complete FHIR R4 scheduling system with HL7v2 ingestion and CLI tools

[Copilot]

This PR implements a comprehensive TypeScript + Fastify server that provides a FHIR R4-compliant REST API for scheduling operations, supporting Schedule, Slot, and Appointment resources as specified in the requirements.

Key Features Implemented

FHIR R4 RESTful API

• Complete CRUD operations for Schedule, Slot, and Appointment resources
• FHIR-compliant responses with proper Bundle formatting
• Search parameters supporting filters by service type, status, date ranges, and actors
• Proper HTTP status codes and error handling with OperationOutcome resources

HL7v2 SIU Message Processing

• POST /$hl7v2-ingest endpoint for ingesting SIU^S12, S13, S15 messages
• Message parsing that converts HL7v2 segments to FHIR resources
• Operation mapping (create/update/delete) based on message type

Pluggable Backend Architecture

• FhirStore interface enabling swappable backend implementations
• Working in-memory simulator with sample data (Dr. Smith, X-Ray, EKG schedules)
• Stub implementations for MongoDB, MySQL, PostgreSQL, MSSQL
• Environment-based selection via .env configuration

OpenAPI 3.1 Documentation

• Swagger UI available at /docs with interactive API documentation
• Categorized endpoints organized by resource type and functionality
• Complete schemas for all request/response objects

Test Mode Operations

• Data simulation via POST /$simulate-week generating provider schedules
• Data clearing with DELETE /Schedule and DELETE /Slot endpoints
• Environment gating ensuring test operations only work when enabled

Command Line Tools

• search-slots.js - Search available appointments by service type (EKG, X-Ray, GP)
• book-appointment.js - Book appointments with slot validation
• demo.sh - Complete workflow demonstration showing search → book → verify cycle

Authentication Framework

• Bearer token plugin ready for SMART-on-FHIR integration
• Token generation and introspection endpoints
• Public path configuration for health checks and documentation

Example Usage

# Search for EKG appointments
node cli/search-slots.js --service=EKG

# Book an appointment
node cli/book-appointment.js --slot=slot-ekg-123 --patient=patient-456

# Run complete demo workflow
./examples/demo.sh

# Generate test data
curl -X POST http://localhost:3000/\$simulate-week \
  -d '{"providerId": "dr-test"}'

System Architecture

The implementation uses a clean, modular architecture:

• Type-safe FHIR resources with comprehensive TypeScript definitions
• Pluggable store pattern allowing easy integration with existing systems
• Fastify-based server with proper error handling and logging
• Environment-driven configuration for different deployment scenarios

The simulator backend comes pre-loaded with realistic test data including 150+ available slots across three service types, demonstrating the complete appointment booking workflow.

Fixes #1.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[awatson1978]

Additional features to consider:

- RFC 7523 - JWT/JWK Tokens (for System / Back End Access)
- Access Control Lists
- JSON-RPC instead of Meteor methods?

FHIR Resource collections that may be relevant to implement:

• Endpoint
• Organization
• OperationOutcome
• SearchParameter
• ConceptMap
• StructureMap
• CodeSystem
• ValueSet
• Permission
• AuditEvent

[awatson1978]

Was able to get the Encounters mapped into Appointments, and a basic FHIR Calendar setup for quality assurance.

[awatson1978]

Hi,
So, I've managed to piece together a first draft of the FHIR Together scheduling server. Refactored the NodeOnFHIR server to use Fastify instead of Express, have the sample data loaded, all the CRUD in place, SMART on FHIR support, Swagger, etc. Have a copy of it that has a front-end UI, and a copy that is headless and server-only (although, even Swagger ships with it's own rendering system).

The one caveat is that it's still using the Meteor build tools. I'm pausing at this moment, because when we feed this into the LLMs to write into Fastify, and I guess the NPM build tool, I worry that we're going to have some breaking changes. I also want to circle back around and discuss the licensing approach.

I've got family visiting next week, and this trip to Japan is fast approaching; so this may be something of a pause point, until we sort some details out. But just wanted to check in, provide an update, and share that we have a Fastify based Appointment scheduling server available. Just need to discuss market positioning and licensing a bit more.

Abbie

---

FHIR R4 RESTful API

• Complete CRUD operations for Schedule, Slot, and Appointment resources
• FHIR-compliant responses with proper Bundle formatting
• Search parameters supporting filters by service type, status, date ranges, and actors
• Proper HTTP status codes and error handling with OperationOutcome resources

HL7v2 SIU Message Processing

• TCP based HL7 v2 support for SIU^S12, S13, S15 messages
• POST /$hl7v2-ingest endpoint for ingesting SIU^S12, S13, S15 messages
• Message parsing that converts HL7v2 segments to FHIR resources
• Operation mapping (create/update/delete) based on message type

Pluggable Backend Architecture

• FhirStore interface enabling swappable backend implementations
• Support for Sythea patient data simulator (Dr. Smith, X-Ray, EKG schedules)
• Working in-memory simulator with sample data (Dr. Smith, X-Ray, EKG schedules)
• Stub implementations for MongoDB, MySQL, PostgreSQL, MSSQL
• Environment-based selection via .env configuration

OpenAPI 3.1 Documentation

• Swagger UI available at /api-docs with interactive API documentation
• Categorized endpoints organized by resource type and functionality
• Complete schemas for all request/response objects

Test Mode Operations

• Data simulation via POST /$simulate-week generating provider schedules
• Data clearing with DELETE /Schedule and DELETE /Slot endpoints
• Environment gating ensuring test operations only work when enabled

Command Line Tools

• search-slots.js - Search available appointments by service type (EKG, X-Ray, GP)
• book-appointment.js - Book appointments with slot validation
• demo.sh - Complete workflow demonstration showing search → book → verify cycle

Authentication Framework

• Bearer token plugin ready for SMART-on-FHIR integration
• Token generation and introspection endpoints
• Public path configuration for health checks and documentation

---

Screenshots

[horner]

@awatson1978 Sorry! I am just now coming to see this! Thank you for doing this.