Design the backend that receives HL7 v2 messages from hospital systems: an MLLP bridge in front of an HTTP endpoint, original-mode ACKs, duplicate control IDs, raw message storage, ADT events and a census that tolerates out-of-order delivery, then build it in Go with Encore.

Most hospital systems still send admits, transfers and discharges as HL7 v2 messages over MLLP, and expect an acknowledgment within seconds. A first receiver parses each message and writes a row.
Then a lost ACK brings a resend and a second admit, and a late discharge leaves a patient on the census. This guide designs ingestion that handles those cases, then builds it in Go with Encore.
An HL7 v2 message is a set of segments separated by carriage returns, each a list of fields separated by |, with components inside fields separated by ^. An admit looks like this:
MSH|^~\&|HISADT|STMARYS|CENSUS|ACME|20261120083000+0100||ADT^A01^ADT_A01|MSG00042|P|2.5.1 EVN|A01|20261120082955 PID|1||483920^^^STMARYS^MR||DOE^JANE||19800214|F PV1|1|I|4WEST^402^1
MSH is the header: sending application and facility in MSH-3 and MSH-4, the message time in MSH-7, the type ADT^A01 in MSH-9 and the control ID MSG00042 in MSH-10. PID-3 carries the medical record number and PV1-3 the ward, room and bed. Numbering is the first trap: in MSH, the field separator itself is MSH-1, so a naive split is off by one for that segment only.
MLLP wraps each message in a start byte 0x0B and ends it with 0x1C 0x0D on a long-lived TCP connection, usually over a VPN to the hospital. The sender writes one message and waits for the ACK before sending the next.
Running that listener inside the application couples your deploys to connections the hospital opens and rarely reopens gracefully. A thin bridge keeps the TCP side small and stable: it unwraps each message, POSTs it to the ingestion endpoint and writes the body of the response, the ACK, back over the connection. Teams use an integration engine channel for this or a short custom program. Google publishes an open source MLLP adapter, but it forwards to the Cloud Healthcare API HL7v2 store rather than to your own endpoint, as its setup guide shows. Mirth Connect, a common choice, became commercial-only with version 4.6 in March 2025, which is worth knowing before you pick it.
The ACK is a message too: an MSH back to the sender and an MSA segment with a code and the original control ID. In original acknowledgment mode the code is AA when you accepted the message, AE when something failed on your side and a resend may succeed, and AR when the message itself is unacceptable.
Get the split wrong and the sender behaves badly in both directions. Answering AR to a database timeout drops a message the hospital believes was rejected for content. Answering AE to an unsupported message type makes the sender retry forever and block every message behind it. Only acknowledge AA after the message is durably stored.
A sender that does not get an ACK in time resends with the same MSH-10, so store messages under a unique key of sending facility and control ID. A repeat of a message you already processed gets AA again and no second event. A repeat of one you stored but failed to publish should publish it, so track a status per message instead of treating "row exists" as "done".
Ordering needs the same care, because once events go through a queue with at-least-once delivery, a transfer can be processed after the discharge that followed it. Each consumer should compare the event time from MSH-7 with the last time applied for that patient and skip older events, which also makes redelivery harmless.
Keep every original message unchanged in a private bucket keyed by facility, date and control ID. When the parser has a bug, or a downstream consumer needs a field you did not extract, you replay from storage instead of asking the hospital to resend a month of traffic.
These messages contain patient identifiers, names and dates of birth. Log control IDs and message types, not bodies, keep the bucket private, and restrict who can read it. Compliance obligations for that data stay with your organization and your agreements with the sending facility, whichever platform runs the code.
Encore is a backend framework with built-in infrastructure, and here a Go service declares its database, a private object storage bucket for raw messages, a Pub/Sub topic for ADT events and a secret for the bridge token, and Encore provisions them in your AWS or GCP account. Encore services expose HTTP endpoints, so the MLLP bridge described above runs in front of the service.

Run in your terminal to get started locally.
The migration creates the message log and the census:
-- hl7/migrations/1_create_tables.up.sql
CREATE TABLE messages (
sending_facility TEXT NOT NULL,
control_id TEXT NOT NULL, -- MSH-10
message_type TEXT NOT NULL, -- MSH-9, e.g. ADT^A01
raw_key TEXT NOT NULL, -- object key of the original message
status TEXT NOT NULL DEFAULT 'received', -- received | published
received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (sending_facility, control_id)
);
CREATE TABLE encounters (
facility TEXT NOT NULL,
patient_mrn TEXT NOT NULL, -- PID-3.1
location TEXT, -- PV1-3, NULL after discharge
state TEXT NOT NULL, -- admitted | discharged
last_event_at TIMESTAMPTZ NOT NULL, -- MSH-7 of the last applied event
PRIMARY KEY (facility, patient_mrn)
);
A small reader covers the fields this service needs, with MSH shifted so that field numbers match the spec, and builds the ACK. A full parser library is worth it once you handle escape sequences and repeating fields, but the shape stays the same:
// hl7/er7/er7.go: a small HL7 v2 (ER7) reader for the fields this service uses.
package er7
import (
"errors"
"strings"
"time"
)
type Message struct {
segments map[string][][]string // segment id -> occurrences -> fields
}
// Parse splits a message into segments (\r) and fields (|).
// MSH is shifted so that Field("MSH", 9) returns MSH-9, as in the spec.
func Parse(raw string) (*Message, error) {
raw = strings.ReplaceAll(strings.TrimSpace(raw), "\n", "\r")
if !strings.HasPrefix(raw, "MSH|") {
return nil, errors.New("message does not start with MSH|")
}
m := &Message{segments: map[string][][]string{}}
for _, seg := range strings.Split(raw, "\r") {
if seg == "" {
continue
}
fields := strings.Split(seg, "|")
if fields[0] == "MSH" {
fields = append([]string{"MSH", "|"}, fields[1:]...)
}
m.segments[fields[0]] = append(m.segments[fields[0]], fields)
}
return m, nil
}
// Field returns field n of the first occurrence of a segment, or "".
func (m *Message) Field(seg string, n int) string {
occ := m.segments[seg]
if len(occ) == 0 || n >= len(occ[0]) {
return ""
}
return occ[0][n]
}
// Component returns component c (1-based) of a field, split on ^.
func (m *Message) Component(seg string, n, c int) string {
parts := strings.Split(m.Field(seg, n), "^")
if c-1 < len(parts) {
return parts[c-1]
}
return ""
}
// Time parses an HL7 DTM such as 20261120083000 or 202611200830+0100.
func Time(v string) (time.Time, error) {
for _, layout := range []string{"20060102150405-0700", "200601021504-0700", "20060102150405", "200601021504", "20060102"} {
if t, err := time.Parse(layout, v); err == nil {
return t, nil
}
}
return time.Time{}, errors.New("bad HL7 timestamp: " + v)
}
// Ack builds an original-mode acknowledgment for msg with code AA, AE or AR.
func Ack(msg *Message, code, controlID string, now time.Time) string {
msh := strings.Join([]string{
"MSH", "^~\\&",
msg.Field("MSH", 5), msg.Field("MSH", 6), // our app and facility, from the receiver fields
msg.Field("MSH", 3), msg.Field("MSH", 4), // back to the sender
now.UTC().Format("20060102150405"), "",
"ACK^" + msg.Component("MSH", 9, 2) + "^ACK",
controlID, msg.Field("MSH", 11), msg.Field("MSH", 12),
}, "|")
return msh + "\rMSA|" + code + "|" + msg.Field("MSH", 10) + "\r"
}
The raw endpoint checks the bridge token, stores the original, records the message under its control ID, publishes the ADT event and answers with the ACK. Each failure maps to AE or AR as described above:
// hl7/hl7.go
package hl7
import (
"bytes"
"context"
"crypto/subtle"
"fmt"
"io"
"net/http"
"time"
"encore.app/hl7/er7"
"encore.dev/pubsub"
"encore.dev/rlog"
"encore.dev/storage/objects"
"encore.dev/storage/sqldb"
)
var secrets struct {
BridgeToken string // shared with the MLLP bridge that forwards messages
}
var db = sqldb.NewDatabase("hl7", sqldb.DatabaseConfig{Migrations: "./migrations"})
// Original messages, kept unchanged for replay and audits. Private bucket.
var Raw = objects.NewBucket("hl7-raw", objects.BucketConfig{Versioned: false})
type ADTEvent struct {
Facility string `json:"facility"`
ControlID string `json:"control_id"`
Trigger string `json:"trigger"` // A01 admit, A02 transfer, A03 discharge, A08 update
PatientMRN string `json:"patient_mrn"`
Location string `json:"location"`
OccurredAt time.Time `json:"occurred_at"`
}
var ADTEvents = pubsub.NewTopic[*ADTEvent]("adt-events", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
// Receive takes one ER7 message from the bridge and returns the HL7 ACK
// the bridge relays to the sender over MLLP.
//
//encore:api public raw method=POST path=/hl7/messages
func Receive(w http.ResponseWriter, req *http.Request) {
token := req.Header.Get("X-Bridge-Token")
if subtle.ConstantTimeCompare([]byte(token), []byte(secrets.BridgeToken)) != 1 {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
body, err := io.ReadAll(io.LimitReader(req.Body, 1<<20))
if err != nil {
http.Error(w, "read error", http.StatusBadRequest)
return
}
msg, err := er7.Parse(string(body))
if err != nil {
http.Error(w, err.Error(), http.StatusBadRequest) // no MSH, nothing to ACK
return
}
ack := func(code string) {
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
io.WriteString(w, er7.Ack(msg, code, "ACK"+msg.Field("MSH", 10), time.Now()))
}
ctx := req.Context()
facility, controlID := msg.Field("MSH", 4), msg.Field("MSH", 10)
evt, err := toEvent(msg)
if err != nil {
rlog.Warn("rejecting message", "facility", facility, "control_id", controlID, "err", err)
ack("AR") // the sender should not resend this unchanged
return
}
// Store the original first, under a key derived from the control ID,
// so a retry overwrites the same object instead of creating a new one.
key := fmt.Sprintf("%s/%s/%s.hl7", facility, evt.OccurredAt.UTC().Format("2006/01/02"), controlID)
wr := Raw.Upload(ctx, key, objects.WithUploadAttrs(objects.UploadAttrs{ContentType: "text/plain; charset=utf-8"}))
if _, err := io.Copy(wr, bytes.NewReader(body)); err != nil {
wr.Abort(err)
ack("AE")
return
}
if err := wr.Close(); err != nil {
ack("AE")
return
}
// Senders resend when an ACK is lost. A repeat of a published message is
// acknowledged again without a second event.
var status string
err = db.QueryRow(ctx, `
INSERT INTO messages (sending_facility, control_id, message_type, raw_key)
VALUES ($1, $2, $3, $4)
ON CONFLICT (sending_facility, control_id)
DO UPDATE SET raw_key = EXCLUDED.raw_key
RETURNING status`,
facility, controlID, msg.Field("MSH", 9), key).Scan(&status)
if err != nil {
ack("AE")
return
}
if status == "published" {
ack("AA")
return
}
if _, err := ADTEvents.Publish(ctx, evt); err != nil {
ack("AE") // the row stays 'received', so the resend publishes it
return
}
if _, err := db.Exec(ctx, `UPDATE messages SET status = 'published'
WHERE sending_facility = $1 AND control_id = $2`, facility, controlID); err != nil {
rlog.Error("marking message published", "control_id", controlID, "err", err)
}
ack("AA")
}
func toEvent(msg *er7.Message) (*ADTEvent, error) {
if msg.Component("MSH", 9, 1) != "ADT" {
return nil, fmt.Errorf("unsupported message type %q", msg.Field("MSH", 9))
}
occurred, err := er7.Time(msg.Field("MSH", 7))
if err != nil {
return nil, err
}
mrn := msg.Component("PID", 3, 1)
if mrn == "" || msg.Field("MSH", 10) == "" {
return nil, fmt.Errorf("missing PID-3 or MSH-10")
}
return &ADTEvent{
Facility: msg.Field("MSH", 4),
ControlID: msg.Field("MSH", 10),
Trigger: msg.Component("MSH", 9, 2),
PatientMRN: mrn,
Location: msg.Component("PV1", 3, 1) + "-" + msg.Component("PV1", 3, 2),
OccurredAt: occurred,
}, nil
}
type CensusEntry struct {
PatientMRN string `json:"patient_mrn"`
Location string `json:"location"`
}
type CensusResponse struct {
Patients []CensusEntry `json:"patients"`
}
// Census lists admitted patients at a facility. Private: other services only.
//
//encore:api private method=GET path=/hl7/census/:facility
func Census(ctx context.Context, facility string) (*CensusResponse, error) {
rows, err := db.Query(ctx, `SELECT patient_mrn, location FROM encounters
WHERE facility = $1 AND state = 'admitted' ORDER BY location`, facility)
if err != nil {
return nil, err
}
defer rows.Close()
out := &CensusResponse{}
for rows.Next() {
var e CensusEntry
if err := rows.Scan(&e.PatientMRN, &e.Location); err != nil {
return nil, err
}
out.Patients = append(out.Patients, e)
}
return out, rows.Err()
}
The subscriber applies admits, transfers and discharges, and the WHERE clause on last_event_at drops any event older than the one already applied:
// hl7/census.go
package hl7
import (
"context"
"encore.dev/pubsub"
)
var _ = pubsub.NewSubscription(ADTEvents, "update-census", pubsub.SubscriptionConfig[*ADTEvent]{
Handler: updateCensus,
})
// updateCensus applies admits, transfers and discharges to the current census.
// Delivery is at least once and not ordered, so each write only applies when
// the event is newer than the last one applied for that patient.
func updateCensus(ctx context.Context, e *ADTEvent) error {
var state string
var location *string
switch e.Trigger {
case "A01", "A02", "A08":
state, location = "admitted", &e.Location
case "A03":
state = "discharged"
default:
return nil // other triggers are stored but do not change the census
}
_, err := db.Exec(ctx, `
INSERT INTO encounters (facility, patient_mrn, location, state, last_event_at)
VALUES ($1, $2, $3, $4, $5)
ON CONFLICT (facility, patient_mrn) DO UPDATE
SET location = EXCLUDED.location, state = EXCLUDED.state,
last_event_at = EXCLUDED.last_event_at
WHERE encounters.last_event_at < EXCLUDED.last_event_at`,
e.Facility, e.PatientMRN, location, state, e.OccurredAt)
return err
}
encore run starts a local Postgres, the bucket and the topic, so you can POST a sample message with the token header and get an ACK back. The reader has plain Go tests that run with go test ./hl7/er7, and the service tests run under encore test. On deploy, the database runs on RDS or Cloud SQL, the bucket on S3 or Cloud Storage and the topic on SNS and SQS or GCP Pub/Sub, and Encore provisions an IAM role for the service.
A coding agent adding a bed-board service subscribes to adt-events in Go and runs both services locally in the same change, without provisioning a queue or granting access to it in a separate step.
On AWS the same design is an ECS service behind an internal load balancer, an RDS Postgres database, a private S3 bucket with a bucket policy for the service's task role, an SNS topic with an SQS queue and dead-letter queue per consumer, and a Secrets Manager secret for the bridge token, all defined in Terraform. On GCP it maps to Cloud Run, Cloud SQL, Cloud Storage and Pub/Sub. The application code is close to the Go above with the SDK calls swapped in, and most of the extra work is the IAM, networking and queue configuration around it.
Hospital systems send HL7 v2 over MLLP, a TCP framing with a start byte and two end bytes. Run an MLLP listener as a thin bridge that unwraps each message, POSTs it to an HTTP endpoint and writes the HL7 ACK from the response back over the connection. The application logic then lives behind ordinary HTTP.
In original acknowledgment mode, MSA-1 is AA when the receiver accepted the message, AE when it hit an error and the sender may retry, and AR when it rejected the message, for example an unsupported type or a missing required field, which the sender should not resend unchanged.
Senders resend when they do not get an ACK in time, with the same MSH-10 control ID. Store messages under a unique key of sending facility and control ID, acknowledge a repeat with AA, and only publish downstream events for the first copy.
With Encore, declare the database, a private bucket for raw messages, an ADT event topic and a secret for the bridge token in Go. A raw endpoint parses, stores and acknowledges each message, a subscription updates the census, and deploys provision the database, bucket and topic in your own AWS or GCP account.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.