# HMIS Documentation

> Operational and developer documentation for the HMIS platform.

## Docs

- [List assigned branches](https://hmis-docs.derrickmugabwa.dev/api-reference/branches.md): List active branches assigned to the authenticated user.
- [List assigned clinics](https://hmis-docs.derrickmugabwa.dev/api-reference/clinics.md): List active clinics assigned to the authenticated user.
- [Get the active organization](https://hmis-docs.derrickmugabwa.dev/api-reference/foundation/get-the-active-organization.md): Returns the active HMIS organization. Requires `organization:read`.
- [Get the authenticated user](https://hmis-docs.derrickmugabwa.dev/api-reference/foundation/get-the-authenticated-user.md): Returns the authenticated user and assigned access context. Requires `hmis:read`.
- [List active services](https://hmis-docs.derrickmugabwa.dev/api-reference/foundation/list-active-services.md): Returns active services with account-head and service-section context. Results are paginated at 50 services per page. Requires `hmis:read`.
- [List assigned active branches](https://hmis-docs.derrickmugabwa.dev/api-reference/foundation/list-assigned-active-branches.md): Returns active branches assigned to the authenticated user. Requires `organization:read`.
- [List assigned active clinics](https://hmis-docs.derrickmugabwa.dev/api-reference/foundation/list-assigned-active-clinics.md): Returns active clinics assigned to the authenticated user. Requires `hmis:read`.
- [List patients](https://hmis-docs.derrickmugabwa.dev/api-reference/foundation/list-patients.md): Returns patients visible through the user's active clinic assignments. Results are paginated at 25 patients per page. Requires `patients:read`.
- [Ingest analyzer results](https://hmis-docs.derrickmugabwa.dev/api-reference/laboratory-integration/ingest-analyzer-results.md): Ingests a normalized analyzer result message. The message identity is `instrument_code + message_id`; identical replays are idempotent and changed replays return a conflict. Requires `laboratory:results:write`. Rate limited to 120 requests per minute per authenticated user and IP.
- [Look up a laboratory worklist](https://hmis-docs.derrickmugabwa.dev/api-reference/laboratory-integration/look-up-a-laboratory-worklist.md): Returns active mapped tests for a dispatched specimen and instrument. Requires `laboratory:worklists:read`. Rate limited to 120 requests per minute per authenticated user and IP.
- [Ingest laboratory results](https://hmis-docs.derrickmugabwa.dev/api-reference/laboratory-results.md): Submit normalized analyzer results to HMIS.
- [Look up a laboratory worklist](https://hmis-docs.derrickmugabwa.dev/api-reference/laboratory-worklist.md): Retrieve mapped analyzer tests for a dispatched specimen.
- [Get the authenticated user](https://hmis-docs.derrickmugabwa.dev/api-reference/me.md): Inspect the current user and assigned HMIS access context.
- [Get the active organization](https://hmis-docs.derrickmugabwa.dev/api-reference/organization.md): Retrieve the active HMIS organization.
- [API reference overview](https://hmis-docs.derrickmugabwa.dev/api-reference/overview.md): Interactive reference for the implemented HMIS API.
- [List patients](https://hmis-docs.derrickmugabwa.dev/api-reference/patients.md): List patients visible through the authenticated user's clinic assignments.
- [Ingest a PACS study event](https://hmis-docs.derrickmugabwa.dev/api-reference/radiology-integration/ingest-a-pacs-study-event.md): Links a PACS study to an HMIS radiology examination. The message identity is `pacs_code + message_id`; identical replays are idempotent and changed replays return a conflict. Requires `radiology:studies:write`. Rate limited to 120 requests per minute per authenticated user and IP.
- [Look up a radiology worklist](https://hmis-docs.derrickmugabwa.dev/api-reference/radiology-integration/look-up-a-radiology-worklist.md): Returns the open radiology examination for a PACS endpoint and accession number. Requires `radiology:worklists:read`. Rate limited to 120 requests per minute per authenticated user and IP.
- [Ingest a radiology study](https://hmis-docs.derrickmugabwa.dev/api-reference/radiology-studies.md): Submit a PACS study event to HMIS.
- [Look up a radiology worklist](https://hmis-docs.derrickmugabwa.dev/api-reference/radiology-worklist.md): Retrieve an open radiology examination for a PACS endpoint.
- [List active services](https://hmis-docs.derrickmugabwa.dev/api-reference/services.md): List active HMIS services and billing context.
- [HMIS documentation](https://hmis-docs.derrickmugabwa.dev/introduction.md): The operational and developer knowledge base for HMIS.
- [Architecture](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/architecture.md): The responsibilities and data flow for the laboratory integration.
- [ASTM/TCP results inbound channel](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/channels/astm-results-inbound.md): Receive ASTM-style analyzer results and normalize them for HMIS.
- [HL7/MLLP results and acknowledgement](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/channels/hl7-mllp-results-inbound.md): Receive HL7 ORU results, relay them to HMIS, and return an HL7 AA acknowledgement.
- [Results relay channel](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/channels/results-relay.md): Configure OIE to relay normalized laboratory results to HMIS.
- [Worklist relay channel](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/channels/worklist-relay.md): Configure OIE to relay analyzer barcode lookups to HMIS.
- [HMIS configuration](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/hmis-configuration.md): Configure the clinical records that an analyzer integration needs.
- [Integration context](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/integration-context.md): Confirmed scope, decisions, and current status of Phase 1 laboratory integration.
- [Mock analyzer](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/mock-analyzer.md): Use the local mock analyzer for safe integration training and validation.
- [OIE channels](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/oie-channels.md): Channel roles, boundaries, and documentation requirements.
- [OIE deployment](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/oie-deployment.md): Deploy OIE alongside HMIS without exposing clinical credentials to analyzers.
- [Production readiness](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/production-readiness.md): Conditions required before connecting a real laboratory analyzer.
- [Testing and validation](https://hmis-docs.derrickmugabwa.dev/laboratory-integration/testing-and-validation.md): Acceptance checks for a pilot analyzer integration.
- [Platform architecture](https://hmis-docs.derrickmugabwa.dev/platform/architecture.md): Services, data stores, trust boundaries, and supported production topology for HMIS.
- [Create the Dokploy project](https://hmis-docs.derrickmugabwa.dev/platform/deployment/dokploy-project.md): Connect the HMIS repository and configure its production Docker Compose service.
- [Domains, TLS, and storage](https://hmis-docs.derrickmugabwa.dev/platform/deployment/domains-and-storage.md): Route HMIS services through Dokploy and protect persistent application, integration, and imaging data.
- [Production environment variables](https://hmis-docs.derrickmugabwa.dev/platform/deployment/environment-variables.md): Required Dokploy variables, ownership, safe values, and rotation rules for HMIS services.
- [First production deployment](https://hmis-docs.derrickmugabwa.dev/platform/deployment/first-deployment.md): Deploy HMIS safely, create foundational data, bootstrap the first administrator, and verify service health.
- [Prepare the Dokploy server](https://hmis-docs.derrickmugabwa.dev/platform/deployment/server-preparation.md): Provision, harden, and install the supported single-server production platform.
- [Environment model](https://hmis-docs.derrickmugabwa.dev/platform/environments.md): Required separation and promotion rules for local, staging, and production HMIS environments.
- [Initial hospital configuration](https://hmis-docs.derrickmugabwa.dev/platform/initial-configuration.md): Secure the first account and configure the organization, users, clinical master data, billing, and go-live ownership.
- [Docker Desktop setup](https://hmis-docs.derrickmugabwa.dev/platform/local-development/docker-desktop.md): Run HMIS, OIE, Orthanc, OHIF, and the simulators as a local Compose stack.
- [Local environment and test data](https://hmis-docs.derrickmugabwa.dev/platform/local-development/environment-and-data.md): Configure local HMIS settings and keep development data separate from clinical data.
- [Native Windows setup](https://hmis-docs.derrickmugabwa.dev/platform/local-development/native-windows.md): Install and run HMIS natively on a Windows development workstation.
- [Local verification](https://hmis-docs.derrickmugabwa.dev/platform/local-development/verification.md): Confirm the local application, background processes, and optional integration stack are working.
- [Backup and restore](https://hmis-docs.derrickmugabwa.dev/platform/operations/backup-and-restore.md): Meet the 24-hour RPO and 8-hour RTO with encrypted off-site backups and tested recovery procedures.
- [Production go-live checklist](https://hmis-docs.derrickmugabwa.dev/platform/operations/go-live-checklist.md): Final technical, operational, clinical, security, and recovery gates before HMIS handles live data.
- [Monitoring and maintenance](https://hmis-docs.derrickmugabwa.dev/platform/operations/monitoring-and-maintenance.md): Monitor HMIS availability, background work, databases, storage, certificates, backups, and integrations.
- [Release and rollback](https://hmis-docs.derrickmugabwa.dev/platform/operations/release-and-rollback.md): Promote an approved HMIS release, run migrations safely, verify production, and recover from a failed deployment.
- [Security and incident response](https://hmis-docs.derrickmugabwa.dev/platform/operations/security-and-incidents.md): Protect HMIS infrastructure, credentials, clinical data, administration, and integration endpoints.
- [Deployment troubleshooting](https://hmis-docs.derrickmugabwa.dev/platform/operations/troubleshooting.md): Diagnose common Dokploy, Laravel, database, queue, scheduler, storage, TLS, and integration failures.
- [Optional integrations](https://hmis-docs.derrickmugabwa.dev/platform/optional-integrations.md): Enable OIE, laboratory, Orthanc, and OHIF services without exposing simulators or clinical credentials.
- [Prerequisites](https://hmis-docs.derrickmugabwa.dev/platform/prerequisites.md): Accounts, software, infrastructure, DNS, and operational access required before HMIS setup.
- [Deployment terminology](https://hmis-docs.derrickmugabwa.dev/platform/terminology.md): Terms and identifiers used throughout the HMIS deployment and operations guides.
- [Architecture](https://hmis-docs.derrickmugabwa.dev/radiology-integration/architecture.md): Vendor-neutral responsibilities and data flow for radiology integration.
- [Orthanc stable-study poller](https://hmis-docs.derrickmugabwa.dev/radiology-integration/channels/orthanc-stable-study-poller.md): Convert Orthanc stable-study changes into vendor-neutral study events.
- [PACS study events relay](https://hmis-docs.derrickmugabwa.dev/radiology-integration/channels/study-events-relay.md): Configure the reusable normalized study-event channel from OIE to HMIS.
- [Worklist lookup and publication](https://hmis-docs.derrickmugabwa.dev/radiology-integration/channels/worklist-lookup.md): Configure OIE to retrieve an HMIS accession and create a PACS worklist item.
- [Demo PACS and viewer](https://hmis-docs.derrickmugabwa.dev/radiology-integration/demo-stack.md): Run Orthanc, OHIF, and the mock modality in the Compose demonstration stack.
- [End-to-end testing](https://hmis-docs.derrickmugabwa.dev/radiology-integration/end-to-end-testing.md): Validate the complete HMIS, OIE, PACS, modality, and viewer workflow.
- [HMIS configuration](https://hmis-docs.derrickmugabwa.dev/radiology-integration/hmis-configuration.md): Configure radiology services, PACS endpoints, tokens, and the normalized APIs.
- [Mock modality](https://hmis-docs.derrickmugabwa.dev/radiology-integration/mock-modality.md): Query DICOM worklists and transmit real DICOM sample images in the demo stack.
- [OIE channels](https://hmis-docs.derrickmugabwa.dev/radiology-integration/oie-channels.md): The generic radiology channels and the Orthanc demo adapter.
- [Troubleshooting](https://hmis-docs.derrickmugabwa.dev/radiology-integration/troubleshooting.md): Diagnose the OIE, Orthanc, DICOM worklist, and OHIF issues found during setup.
- [Workflow and statuses](https://hmis-docs.derrickmugabwa.dev/radiology-integration/workflow-and-statuses.md): The shortened radiology workflow from billing through authorization.

## OpenAPI Specs

- [openapi](https://hmis-docs.derrickmugabwa.dev/openapi.yaml)