From 3e00cf88e7a76d3fca74f69bf125211c47526046 Mon Sep 17 00:00:00 2001
From: Markus Thielker <markus@thielker.dev>
Date: Wed, 30 Jul 2025 12:29:58 +0200
Subject: [PATCH] HL7-1: add README.md

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..06185d2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# HL7v2
+
+HL7v2 is a medical communication protocol. This application tries to be a hands-on method for students to get to know
+the communication foundation of almost every medical institution, typically hidden behind software forms.
+
+## How it works
+
+The application is web-based and features an individual number of clients. Every client has an input to construct a
+raw HL7v2 message, build of the message header and an optional number of segments. Each editor has predefined segment
+templates with missing values, which have to be filled in to be sent the message to a different client.
+
+## Architecture
+
+The stack features a SvelteKit application and a Bun websocket server. Communication between clients is only the
+web-socket server, validating each message for a valid format. Only if the message was valid and delivered successfully
+to a different client, the server sends back an acknowledgement and notifies the sending client.
+
+# Getting started
+
+1. Download the sources of the project
+2. Execute `bun install` and `bun run dev` in the root directory
+3. Start customizing the code to your needs
+
+# Deployment
+
+1. Download the compose.yaml file to the machine you want the application to run on.
+2. Copy the sample .env file by running `cp .env.example .env` and adjust the new file to your needs.
+
+    ```env
+    -- public URL of the client used by traefik
+    CLIENT_URL=my.app.com
+    
+    -- public URL of the server used by the client to connect and traefik
+    SERVER_URL=server.my.app.com
+    
+    -- the port the server listens on
+    PORT=8080
+    
+    -- number of ID prefixes (no effect on pool-size)
+    PREFIXES=STA,LAB
+    
+    -- amount of available IDs
+    POOL_SIZE=100
+    ```
+
+3. The compose.yaml file configures Traefik routers with TLS encryption. Customize the settings as needed or just remove
+   them if you are using a different reverse proxy.
+4. Start up the containers using `podman|docker compose up -d`.