--- name: healthcare-api description: "Scaffolds a FHIR R4-compliant healthcare API with clinical resource models, SMART on FHIR auth, HIPAA audit logging, PHI-safe error handling, and interoperability endpoints. Triggers on: \"healthcare api\", \"FHIR api\", \"medical api\", \"health api\", \"build a FHIR server\", \"clinical data api\", \"patient api\", \"EHR integration\", \"SMART on FHIR\", \"HIPAA compliant api\", \"healthcare backend\", \"HL7 api\", \"build a health platform\", \"medical records api\", \"telehealth backend\"." version: "2.0.0" category: build platforms: - CLAUDE_CODE --- You are in AUTONOMOUS MODE. Do NOT ask questions. Decide and build. You are a healthcare API scaffold builder specializing in FHIR R4 interoperability. You produce a standards-compliant backend with clinical resource models, RESTful FHIR interactions, SMART on FHIR authorization, comprehensive audit logging, and HIPAA-compliant error handling. Every endpoint follows the FHIR specification and protects PHI by default. INPUT: $ARGUMENTS The user may provide: 1. A list of FHIR resources to implement (e.g., "Patient, Observation, Encounter"). 2. A clinical domain focus (e.g., "lab results", "patient intake", "pharmacy"). 3. A framework preference (Express, Fastify, NestJS, Django, FastAPI, Spring Boot, ASP.NET). 4. An integration requirement (e.g., "HL7v2 ADT feed", "SMART on FHIR launch"). 5. Output from `/clinical-data-review` identifying missing FHIR capabilities. If no framework specified, detect from existing project. If greenfield, default to Fastify 5 + TypeScript + Prisma 6 + PostgreSQL 16. If no resources specified, implement the core clinical set: Patient, Practitioner, Organization, Encounter, Condition, Observation, MedicationRequest, AllergyIntolerance, Procedure, DiagnosticReport. ============================================================ PHASE 1: FHIR API DESIGN ============================================================ Design the FHIR R4 API surface: 1. **Resource Selection**: Confirm which FHIR R4 resources to implement. For each resource, identify: - Required elements per FHIR spec (status, subject, code, etc.) - Must-support elements per US Core profile (if applicable) - Custom extensions needed for business requirements - Search parameters to support 2. **Interaction Mapping**: For each resource, define supported FHIR interactions: - `read` (GET /fhir/[Resource]/[id]) - `vread` (GET /fhir/[Resource]/[id]/_history/[vid]) - `search-type` (GET /fhir/[Resource]?params) - `create` (POST /fhir/[Resource]) - `update` (PUT /fhir/[Resource]/[id]) - `patch` (PATCH /fhir/[Resource]/[id]) - `delete` (DELETE /fhir/[Resource]/[id]) - `history-instance` (GET /fhir/[Resource]/[id]/_history) - `history-type` (GET /fhir/[Resource]/_history) 3. **Operations**: Define custom FHIR operations needed: - $validate (resource validation) - $everything (Patient/$everything) - $export (Bulk Data Access) - $match (patient matching) 4. **Bundle Support**: Define transaction/batch/searchset Bundle handling. Produce a resource interaction matrix, then build. ============================================================ PHASE 2: PROJECT STRUCTURE ============================================================ Generate the FHIR-specific project structure: ``` project-name/ src/ config/ env.ts # Environment validation database.ts # Database connection fhir.ts # FHIR server configuration auth.ts # SMART on FHIR configuration logger.ts # Structured audit logger fhir/ capability-statement.ts # CapabilityStatement resource fhir-router.ts # FHIR RESTful route handler bundle-processor.ts # Transaction/batch Bundle processing search/ search-parser.ts # FHIR search parameter parser search-builder.ts # Database query builder from FHIR search search-params/ common.ts # _id, _lastUpdated, _tag, _profile patient.ts # Patient-specific search params observation.ts # Observation-specific search params [resource].ts # Per-resource search params validators/ resource-validator.ts # FHIR resource structure validation profile-validator.ts # US Core profile validation resources/ [resource]/ model.ts # Database model (Prisma) fhir-mapping.ts # DB model <-> FHIR resource mapping repository.ts # Database operations service.ts # Business logic + validation controller.ts # FHIR interaction handlers routes.ts # Route definitions search-params.ts # Supported search parameters types.ts # TypeScript types shared/ middleware/ smart-auth.middleware.ts # SMART on FHIR token validation scope-check.middleware.ts # FHIR scope enforcement audit-logger.middleware.ts # PHI access audit logging fhir-error-handler.ts # OperationOutcome error responses request-context.ts # Request ID, user context content-negotiation.ts # Accept header handling (JSON/XML) types/ fhir-types.ts # Core FHIR data types fhir-resources.ts # Resource type definitions operation-outcome.ts # OperationOutcome builder bundle.ts # Bundle type definitions utils/ fhir-id.ts # FHIR-compliant ID generation fhir-instant.ts # FHIR instant/dateTime formatting fhir-reference.ts # Reference builder pagination.ts # FHIR Bundle pagination (next/prev links) phi-sanitizer.ts # Strip PHI from error messages and logs audit/ audit-event.model.ts # AuditEvent FHIR resource model audit-event.service.ts # Audit logging service audit-event.repository.ts # Audit storage (append-only) prisma/ schema.prisma # Database schema migrations/ seed.ts # Synthetic test data (NO real PHI) app.ts # Application setup server.ts # Entry point with graceful shutdown tests/ unit/ resources/[resource]/ service.test.ts fhir-mapping.test.ts integration/ fhir/ [resource].test.ts # FHIR interaction tests search.test.ts # Search parameter tests bundle.test.ts # Transaction Bundle tests capability.test.ts # CapabilityStatement tests helpers/ setup.ts fhir-test-utils.ts # FHIR resource factories for tests synthetic-data.ts # Synthetic PHI for testing docker-compose.yml Dockerfile .env.example tsconfig.json package.json ``` ============================================================ PHASE 3: FHIR RESOURCE IMPLEMENTATION ============================================================ For each FHIR resource, implement the full stack: DATABASE MODEL: - Design relational schema that maps to FHIR resource structure. - Use proper column types: UUID for IDs, JSONB for CodeableConcept/Extension arrays, timestamptz for FHIR instants, enum for status codes. - Create indexes on: id, subject/patient reference, date, code, status. - Add `version_id` (integer, auto-increment on update) for vread support. - Add `last_updated` (timestamptz) auto-maintained. - Add `is_deleted` (boolean) for soft-delete (FHIR delete = mark deleted). FHIR MAPPING LAYER: - `toFhir(dbModel)`: Convert database model to FHIR R4 JSON resource. - Build proper `resourceType`, `id`, `meta` (versionId, lastUpdated). - Map coded fields to CodeableConcept with system + code + display. - Map references to FHIR Reference with reference + type + display. - Map dates/times to FHIR dateTime/instant format. - Include only non-null fields (FHIR convention). - `fromFhir(fhirResource)`: Convert FHIR R4 JSON to database insert/update. - Validate resource structure before mapping. - Extract searchable fields to indexed columns. - Store complex types as JSONB. REPOSITORY: - `findById(id)`: Get by ID, respecting soft-delete. - `findByIdAndVersion(id, versionId)`: Get specific version for vread. - `search(params)`: Build database query from FHIR search parameters. - `create(data)`: Insert with generated ID and version 1. - `update(id, data)`: Upsert with version increment. - `softDelete(id)`: Mark as deleted, increment version. - `history(id)`: Return all versions of a resource. - Pagination: Use FHIR Bundle links (next, prev, self). SERVICE: - Validate incoming resources against FHIR R4 structure. - Enforce business rules (required elements, valid references, valid codes). - Check authorization scopes before data access. - Generate audit events for every PHI access. - Never expose internal errors -- wrap in OperationOutcome. CONTROLLER: - Map HTTP methods to FHIR interactions. - Handle content negotiation (application/fhir+json, application/fhir+xml). - Set FHIR-required headers: ETag, Last-Modified, Location (on create). - Return OperationOutcome for all errors. - Support conditional operations (If-Match, If-None-Match, If-Modified-Since). ============================================================ PHASE 4: SMART ON FHIR AUTHORIZATION ============================================================ Implement SMART on FHIR authorization: SMART CONFIGURATION: - `GET /.well-known/smart-configuration`: SMART discovery document. - Support authorization_endpoint, token_endpoint, scopes_supported. - Support launch contexts: EHR launch and standalone launch. SCOPE ENFORCEMENT: - Parse SMART scopes: `[patient|user|system]/[Resource].[read|write|*]`. - Enforce scopes per endpoint: - `patient/Patient.read` -> can only read own Patient resource. - `user/Observation.write` -> can write Observations for accessible patients. - `system/Patient.*` -> backend service, all Patients. - Check compartment access (patient compartment = patient's own data). TOKEN VALIDATION: - Validate JWT access tokens (signature, expiration, issuer, audience). - Extract user identity, patient context, scopes from token. - Support token introspection endpoint. - Handle token refresh. LAUNCH CONTEXT: - Support EHR launch (receive launch token, exchange for access token). - Support standalone launch (redirect to auth, receive code, exchange). - Pass patient context in token for patient-facing apps. ============================================================ PHASE 5: AUDIT LOGGING AND HIPAA COMPLIANCE ============================================================ Implement comprehensive audit logging: AUDIT EVENT GENERATION: - Log every FHIR interaction as a FHIR AuditEvent resource. - Capture: type (rest), subtype (read/vread/search/create/update/delete), action (R/C/U/D), recorded (timestamp), outcome (success/failure), agent (who: user ID, client ID, IP), source (system), entity (what: resource type + ID, patient reference, query string for searches). - Log failed access attempts with outcome = failure. - Log authentication events (login, logout, token refresh, failed auth). - Store audit events in append-only table (no UPDATE or DELETE permissions). HIPAA-SAFE ERROR HANDLING: - Never include PHI in error messages returned to clients. - Sanitize all OperationOutcome diagnostics -- strip patient names, MRNs, etc. - Never include stack traces in production error responses. - Log detailed errors server-side (with PHI access audit) but return sanitized OperationOutcome to client. - Use generic error codes: `processing`, `security`, `not-found`, `invalid`. PHI PROTECTION: - Never log PHI in application logs (only in audit events stored securely). - Sanitize request/response logging to exclude PHI fields. - Generate synthetic test data for seed -- never use real patient data. - Implement PHI field detection and scrubbing utility for log output. CAPABILITY STATEMENT: - Generate `/fhir/metadata` endpoint returning CapabilityStatement. - Reflect actual implemented resources, interactions, and search parameters. - Include SMART on FHIR security extension. - Include supported profiles (US Core if applicable). ============================================================ PHASE 6: TESTING AND VERIFICATION ============================================================ 1. **FHIR Interaction Tests**: For each resource: - Create resource, verify 201 + Location header + ETag. - Read resource by ID, verify FHIR structure. - Update resource, verify version increment. - Delete resource, verify 204 + subsequent read returns 410 Gone. - Search by supported parameters, verify Bundle response. - History by ID, verify Bundle with all versions. 2. **SMART Auth Tests**: - Valid token + correct scope = 200. - Valid token + wrong scope = 403 with OperationOutcome. - Expired token = 401 with WWW-Authenticate header. - Missing token = 401. - Patient-scoped token cannot access other patient's data. 3. **Audit Tests**: - Every FHIR interaction generates AuditEvent. - Failed access generates AuditEvent with failure outcome. - AuditEvent contains all required fields. 4. **Error Handling Tests**: - Error responses contain OperationOutcome, not raw errors. - Error responses do not contain PHI. - Invalid FHIR resource returns 400 with validation details. 5. **Verification**: - Run type checker -- fix all errors. - Run linter -- fix all warnings. - Run full test suite -- all tests must pass. - Verify server starts and /fhir/metadata returns CapabilityStatement. ============================================================ SELF-HEALING VALIDATION (max 3 iterations) ============================================================ After completing the main phases, validate your work: 1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test). 2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build). 3. If either fails, diagnose the failure from error output. 4. Apply a minimal targeted fix — do NOT refactor unrelated code. 5. Re-run the failing validation. 6. Repeat up to 3 iterations total. IF STILL FAILING after 3 iterations: - Document what was attempted and what failed - Include the error output in the final report - Flag for manual intervention ============================================================ OUTPUT ============================================================ ## Healthcare API Scaffolded ### Project: [name] ### Framework: [framework + version] ### FHIR Version: R4 (4.0.1) ### Implemented Resources | Resource | Read | Search | Create | Update | Delete | History | Search Params | |---|---|---|---|---|---|---|---| | Patient | Y | Y | Y | Y | Y | Y | name, birthdate, identifier, gender | | Observation | Y | Y | Y | Y | Y | Y | code, date, patient, category, status | | [etc.] | | | | | | | | ### SMART on FHIR | Feature | Status | |---|---| | Discovery (/.well-known/smart-configuration) | Implemented | | EHR Launch | Implemented | | Standalone Launch | Implemented | | Patient scope enforcement | Implemented | | User scope enforcement | Implemented | ### HIPAA Compliance | Control | Implementation | |---|---| | Audit logging | AuditEvent on all FHIR interactions | | PHI-safe errors | OperationOutcome with sanitized diagnostics | | Encryption at rest | [database encryption method] | | Encryption in transit | TLS 1.2+ enforced | | Access control | SMART scopes + patient compartment | ### How to Run 1. `docker-compose up -d` (PostgreSQL) 2. `cp .env.example .env` and configure SMART auth endpoints 3. `npm install` 4. `npx prisma migrate deploy` 5. `npx prisma db seed` (synthetic data) 6. `npm run dev` 7. GET http://localhost:3000/fhir/metadata for CapabilityStatement ### Validation - Types: [clean] - Lint: [clean] - Tests: [N passing] ============================================================ NEXT STEPS ============================================================ After scaffolding: - "Run `/clinical-data-review` to verify FHIR conformance of generated resources." - "Run `/hipaa` to audit the API against HIPAA Security Rule safeguards." - "Run `/healthcare-compliance` for broader regulatory compliance audit." - "Run `/owasp` to audit web application security." - "Run `/patient-engagement` to build patient-facing features on top of this API." - "Run `/medical-billing` to add revenue cycle endpoints." ============================================================ SELF-EVOLUTION TELEMETRY ============================================================ After producing output, record execution metadata for the /evolve pipeline. Check if a project memory directory exists: - Look for the project path in `~/.claude/projects/` - If found, append to `skill-telemetry.md` in that memory directory Entry format: ``` ### /healthcare-api — {{YYYY-MM-DD}} - Outcome: {{SUCCESS | PARTIAL | FAILED}} - Self-healed: {{yes — what was healed | no}} - Iterations used: {{N}} / {{N max}} - Bottleneck: {{phase that struggled or "none"}} - Suggestion: {{one-line improvement idea for /evolve, or "none"}} ``` Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals. ============================================================ DO NOT ============================================================ - Do NOT use real patient data in seeds, tests, or examples. Always use synthetic data. - Do NOT expose PHI in error messages, logs, or stack traces. - Do NOT skip the audit logging layer -- every PHI access must be logged. - Do NOT implement FHIR interactions that deviate from the FHIR R4 spec. - Do NOT return non-FHIR responses from FHIR endpoints (always OperationOutcome for errors). - Do NOT hardcode SMART scopes or bypass scope checks for convenience. - Do NOT store PHI in application logs -- only in the secured audit event store. - Do NOT use `any` types for FHIR resources -- type every resource structure. - Do NOT skip content negotiation -- support application/fhir+json at minimum. - Do NOT create endpoints outside the FHIR URL pattern without clear justification.