> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform architecture

> Services, data stores, trust boundaries, and supported production topology for HMIS.

HMIS is a Laravel application deployed as a multi-service Docker Compose project. Dokploy builds the application image, starts the services, terminates public HTTPS through its proxy, and provides logs and container access.

## Supported topology

The supported production baseline is one hardened Linux server running one Dokploy installation. This is suitable for an initial or small installation when the server has adequate CPU, memory, storage, backup capacity, and operational support.

<Warning>
  This topology is not highly available. A host, storage, or Docker failure can interrupt the entire installation. Move PostgreSQL, imaging storage, and application replicas to redundant infrastructure before the clinical or imaging load exceeds a single server's capacity or the hospital requires an RTO below eight hours.
</Warning>

## Service map

| Service            | Purpose                            | Persistent data                                   | Public access                                                |
| ------------------ | ---------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
| `app`              | Laravel/Apache web and API process | `app-storage`                                     | HTTPS through Dokploy                                        |
| `queue`            | Laravel database queue worker      | Shared application storage and HMIS database      | None                                                         |
| `scheduler`        | Laravel task scheduler             | HMIS database                                     | None                                                         |
| `postgres`         | HMIS PostgreSQL 17 database        | `postgres-data`                                   | None                                                         |
| `oie`              | Open Integration Engine            | `oie-appdata`, `oie-extensions`, and OIE database | Administrator access only; analyzer listeners remain private |
| `oie-postgres`     | OIE PostgreSQL 17 database         | `oie-postgres-data`                               | None                                                         |
| `orthanc`          | PACS and DICOMweb service          | `orthanc-storage` and Orthanc database            | DICOM only through an approved private network               |
| `orthanc-postgres` | Orthanc PostgreSQL 17 database     | `orthanc-postgres-data`                           | None                                                         |
| `ohif`             | Browser-based DICOM viewer         | No application volume                             | Protected HTTPS through Dokploy                              |
| `mock-analyzer`    | Laboratory simulator               | None                                              | Local and staging only                                       |
| `mock-modality`    | Radiology simulator                | None                                              | Local and staging only                                       |

## Request and data flow

1. Users connect to the HMIS or OHIF domain over HTTPS.
2. Dokploy routes the request to the relevant container without publishing its database ports.
3. HMIS stores transactional data in PostgreSQL and uploaded files in `app-storage`.
4. The queue worker processes asynchronous work; the scheduler closes expired outpatient visits at `00:01`.
5. When enabled, OIE exchanges orders and results between HMIS and approved devices.
6. Orthanc stores imaging studies and exposes DICOMweb to OHIF on the internal network.

## Trust boundaries

* Expose only SSH, HTTP, and HTTPS on the public firewall.
* Put OIE administrator access behind a VPN, SSH tunnel, IP allow-list, or identity-aware proxy.
* Permit analyzer, MLLP, ASTM, and DICOM traffic only from approved private network ranges.
* Never publish PostgreSQL, Orthanc Explorer, raw DICOMweb, or device listener ports to the internet.
* Store credentials in Dokploy environment variables or the host backup system, never in Git or documentation.

## Capacity boundaries

Begin with at least 4 vCPU, 16 GB RAM, and 200 GB SSD storage for a staging or small production installation that includes integrations. Size imaging storage from expected study volume and retention, not from this minimum. Maintain at least 25% free disk space and alert at 80% utilization.

Review the topology before go-live when any of these conditions applies:

* The installation requires continuous availability during host maintenance.
* The stated RPO of 24 hours or RTO of 8 hours is insufficient.
* Imaging growth could consume the host within 12 months.
* Database workload causes sustained CPU, memory, or I/O saturation.
* Security policy requires separate database, integration, or PACS networks.

## Related guides

* [Environment model](/platform/environments)
* [Server preparation](/platform/deployment/server-preparation)
* [Backup and restore](/platform/operations/backup-and-restore)
* [Security and incidents](/platform/operations/security-and-incidents)