Medical Coding Software for Swiss Hospitals

Version latest

Platform Overview

Server

REST API, WebSocket, session management, audit logging

Spring Boot • Port 8080
🗃

DataServer

ICD-10, CHOP, ATC catalogs, SwissDRG classification data

Spring Boot • Port 8081

Grouper

SwissDRG, TARPSY, ST Reha real-time grouping engine

Spring Boot • Port 8082

CodingUI

React web interface with 14+ data blocks, multilingual

React / Vite • Port 3000

COM DLL

In-process HIS integration for .NET, VB6, VBA, C#, Delphi

Windows • KodeMed.dll

CodingClient

System tray app, WebSocket, webhook, auto-reconnect

Windows • WebView2 • MSI

Security & Compliance

🔒 Authentication

  • OAuth2 / OpenID Connect (SSO)
  • Keycloak, Azure AD, Okta compatible
  • JWT token validation on every request
  • Per-client credentials (DLL, UI, Portal)

🛡 Data Protection

  • GDPR Art. 32 — AES encryption at rest
  • TLS 1.2+ for all network communication
  • No patient data stored on client
  • Configurable data retention policies

📑 Audit & Logging

  • Full audit trail for all coding sessions
  • User, timestamp, action, IP address
  • Structured JSON logs (ELK / Splunk ready)
  • 90-day default retention (configurable)

⚙ Container Security

  • Non-root containers (UID 1000)
  • Read-only root filesystem
  • Drop ALL Linux capabilities
  • Network policies (namespace isolation)

🔑 Licensing

  • RSA-4096 signed offline license file
  • Per-component validation (Server, DataServer, Grouper)
  • License types: DEMO, TRIAL, PRODUCTION
  • API status: GET /api/v1/license/status

Documentation

Deutsch

  • KodeMed GmbH PräsentationPPTX
  • SystemarchitekturPPTX
  • IntegrationsleitfadenPPTX
  • Update- & Lebenszyklus-RichtliniePPTX
  • OpenShift-BereitstellungsrichtliniePPTX

Français

  • Présentation KodeMed GmbHPPTX
  • Architecture du systèmePPTX
  • Guide d’intégrationPPTX
  • Politique de mise à jourPPTX
  • Politique de déploiement OpenShiftPPTX

Italiano

  • Presentazione KodeMed GmbHPPTX
  • Architettura del sistemaPPTX
  • Guida all’integrazionePPTX
  • Politica di aggiornamentoPPTX
  • Politica di distribuzione OpenShiftPPTX

English

  • KodeMed GmbH PresentationPPTX
  • System ArchitecturePPTX
  • Integration GuidePPTX
  • Update & Lifecycle PolicyPPTX
  • OpenShift Deployment PolicyPPTX

Markdown Documentation

  • System Architecture MD
  • Integration Guide MD
  • Update & Lifecycle Policy MD
  • OpenShift Deployment Policy MD

Windows Client

MSI Installer

No admin rights required. Installs per-user to %LOCALAPPDATA%\KodeMed. Supports silent mode for enterprise deployment (GPO, SCCM, Intune).

Download MSI

Silent install:  msiexec /i KodeMed.msi /quiet /norestart SERVERURL="https://kodemed.hospital.ch"

Log in for individual files, documentation, and advanced options.

Windows 10 / 11 .NET Runtime included ~80 MB disk space

Windows Client — Advanced Options

Enterprise deployment (IT administrators)

Silent Install — MSI (GPO / SCCM / Intune)

# Basic — server URL only (language auto-detected, autostart enabled)
msiexec /i KodeMed.msi /quiet /norestart SERVERURL="https://kodemed.hospital.ch"
# Full options — all parameters
msiexec /i KodeMed.msi /quiet /norestart SERVERURL="https://kodemed.hospital.ch" LANGUAGE="de" AUTOSTART=1
# Citrix / shared desktop — disable autostart
msiexec /i KodeMed.msi /quiet /norestart SERVERURL="https://kodemed.hospital.ch" AUTOSTART=0
# Custom install directory
msiexec /i KodeMed.msi /quiet /norestart SERVERURL="https://kodemed.hospital.ch" INSTALLDIR="D:\Apps\KodeMed"
# Silent install with log file (for troubleshooting)
msiexec /i KodeMed.msi /quiet /norestart /l*v "%TEMP%\KodeMed-install.log" SERVERURL="https://kodemed.hospital.ch"
# Uninstall
msiexec /x KodeMed.msi /quiet /norestart

MSI properties: SERVERURL (required) • LANGUAGE — de, fr, it, en (default: auto-detect) • AUTOSTART — 1 or 0 (default: 1) • INSTALLDIR (default: %LOCALAPPDATA%\KodeMed)
Config location: %LOCALAPPDATA%\KodeMed\kodemed-client-config.jsonPrerequisites: Windows 10+, WebView2 Runtime (usually pre-installed)

Individual Files

Linux Server

Server Installation Package

Contains Server, DataServer, GrouperServer, CodingUI, and installer scripts.

$ tar -xzf kodemed-linux-latest.tar.gz
$ sudo ./install-kodemed.sh
Docker 24+ Docker Compose 2.x Linux x86_64

Support

Technical support and documentation: https://demo-docs-kodemed.mieresit.com

Deployment Wizard Docker Compose

This wizard generates a ready-to-use deployment package for your hospital’s on-premise server. Fill in the fields below and click Download ZIP to get:

  • docker-compose.yml — orchestrates all KodeMed services (Server, DataServer, Grouper, CodingUI, PostgreSQL)
  • .env — passwords, URLs, and settings (keep this file secure)
  • runtime-config.js — browser configuration for the CodingUI
1. Public URLs (browser-accessible — used by CodingUI and DLL clients)

These are the URLs your users will access from their browser or DLL client. They must be reachable externally (via reverse proxy, load balancer, or direct).

2. Internal Service URLs (Docker network — usually keep defaults)

These are the internal Docker network URLs used in docker-compose.yml. Keep the defaults unless you use an external reverse proxy or custom network.

3. Database

KodeMed requires PostgreSQL 15+. You can use the bundled container or connect to your hospital’s existing database server.

4. Authentication (OIDC / SSO)

Connect KodeMed to your hospital’s identity provider (Keycloak, Azure AD, Okta, etc.) for single sign-on. Leave blank to configure later.

5. Security & Advanced Options

Optional settings for GDPR compliance, CORS, and logging. Sensible defaults are provided — only change if your infrastructure requires it.

Quick Start

After downloading the ZIP, deploy on your Linux server:

$ unzip kodemed-deployment.zip
$ docker compose up -d
$ docker compose logs -f # watch startup

All services start automatically. The CodingUI will be available on port 3000. Import classification data via the DataServer admin API (port 8081).

Note: The GrouperServer requires specs/ and catalogues/ directories with SwissDRG/TARPSY/ST Reha specification files. Contact support for the grouper data package, or download from SwissDRG.org.

Technical Documentation Confidential

Integration & API

  • GetResults() Return Format MD PPTX

Classification Data Import

Official Swiss medical classification data (ICD-10-GM, CHOP, SwissDRG, TARPSY, ST Reha) can be downloaded from the sources below and imported via the DataServer admin API. See the DevOps Guide §14 for details.

Deployment Architecture

  • Native Linux PNG
  • Docker Compose PNG
  • OpenShift / Kubernetes PNG

DevOps Guide Confidential

Server Administration & Deployment

  • DevOps Guide (DE) PPTX
  • DevOps Guide (FR) PPTX
  • DevOps Guide (IT) PPTX
  • DevOps Guide (EN) PPTX

Markdown Documentation

  • DevOps & Server Admin Guide MD

Troubleshooting

DLL client opens wrong URL (404 on coding page)

KODEMED_PUBLIC_UI_URL is not set. The server returns its own URL instead of the CodingUI URL.

KODEMED_PUBLIC_UI_URL=https://coding-ui.hospital.ch

The server logs a warning at startup: CONFIG ⚠ KODEMED_PUBLIC_UI_URL is not set

WebSocket returns HTTP 200 instead of 101

Reverse proxy is not upgrading WebSocket connections. Enable mod_proxy_wstunnel (Apache) or add Upgrade headers (nginx).

# Apache
a2enmod proxy_wstunnel rewrite
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule ^/ws/(.*) ws://localhost:8080/ws/$1 [P,L]
Portal returns 500 on login

Check oauth2-proxy logs: docker compose logs kodemed-downloads-auth

unauthorized_client → Client secret mismatch with OIDC provider
invalid_scope → Remove groups from OAUTH2_PROXY_SCOPE
invalid_redirect_uri → Check redirect URI matches OIDC client config

Server startup configuration warnings

Check logs after deployment:

docker compose logs kodemed-server | grep "CONFIG"

CONFIG ✓ All public URL configuration present — all good
CONFIG ⚠ KODEMED_PUBLIC_* — specific variable is missing

Required Environment Variables

VariableRequiredPurpose
KODEMED_PUBLIC_UI_URLYesCodingUI URL for browser redirect
KODEMED_PUBLIC_SERVER_URLRecommendedServer URL for DLL clients
KODEMED_PUBLIC_DATASERVER_URLRecommendedDataServer URL for classification data
KODEMED_PUBLIC_WEBSOCKET_URLRecommendedWebSocket URL for real-time communication
OIDC_ISSUER_URIYesOIDC issuer for token validation
CORS_ALLOWED_ORIGINSYesAllowed origins for API requests

Sales Materials Confidential

Presentations & Sales Material

  • KodeMed Sales (DE) PPTX
  • KodeMed Sales (FR) PPTX
  • KodeMed Sales (IT) PPTX
  • KodeMed Sales (EN) PPTX

License Generator Admin + Sales

Generate License File

Fill in the customer details below. The tool generates a signed kodemed.license file ready to send to the customer.

CLI Command

Run this on a machine with the private key and the kodemed-license-cli.jar:


        
        Copied!
      

License CLI Tool

Download the CLI JAR to generate and verify license files.

  • kodemed-license-cli.jar Download JAR
  • Quick Reference java -jar kodemed-license-cli.jar generate --private-key key.pem --type DEMO --org "Hospital" --days 90 --output kodemed.license

Configuration Reference

Complete list of all environment variables, settings, and config keys across all KodeMed components. Use the filter to search.

KodeMed Server Port 8080

Main coding API — Spring Boot backend handling DLL sessions, WebSocket, persistence, webhooks.

Environment VariableDefaultDescription
SERVER_PORT8080HTTP server port
SPRING_PROFILES_ACTIVE(none)Active Spring profiles (use prod for production)
SPRING_DATASOURCE_URLjdbc:h2:mem:kodemedJDBC connection URL (PostgreSQL in prod)
SPRING_DATASOURCE_USERNAMEsaDatabase username
SPRING_DATASOURCE_PASSWORD(empty)Database password
SPRING_DATASOURCE_DRIVER_CLASS_NAMEorg.h2.DriverJDBC driver class (org.postgresql.Driver in prod)
SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE15HikariCP max connection pool size
SPRING_DATASOURCE_HIKARI_MINIMUM_IDLE5HikariCP minimum idle connections
SPRING_DATASOURCE_HIKARI_IDLE_TIMEOUT300000HikariCP idle timeout (ms)
SPRING_DATASOURCE_HIKARI_CONNECTION_TIMEOUT20000HikariCP connection timeout (ms)
SPRING_JPA_HIBERNATE_DDL_AUTOupdateHibernate DDL strategy (consider validate for prod)
KODEMED_AUTH_ENABLEDtrueEnable/disable OAuth2 authentication
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI(Keycloak URL)OIDC issuer URI for JWT validation
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI(Keycloak certs URL)JWK Set URI for JWT validation
CORS_ALLOWED_ORIGINS(empty)Comma-separated CORS allowed origins
WEBSOCKET_ALLOWED_ORIGINS(empty)WebSocket allowed origins
KODEMED_ENCRYPTION_KEY(empty)AES-256 key (base64, 32 bytes). Generate: openssl rand -base64 32
KODEMED_LICENSE_FILE(auto-search)Path to kodemed.license file
KODEMED_PUBLIC_SERVER_URL(auto-detected)Public URL for the server API (returned to DLL)
KODEMED_PUBLIC_DATASERVER_URL(auto-detected)Public URL for DataServer (returned to DLL)
KODEMED_PUBLIC_WEBSOCKET_URL(auto-detected)Public WebSocket URL wss:// (returned to DLL)
KODEMED_PUBLIC_UI_URL(auto-detected)Public URL for CodingUI (returned to DLL)
KODEMED_OAUTH2_REALMkodemedOAuth2 realm name (returned to DLL)
KODEMED_OAUTH2_CLIENT_IDkodemed-dllOAuth2 client ID for DLL authentication
KODEMED_PERSISTENCE_ENABLEDtrueEnable persistent storage of coding sessions
KODEMED_AUDIT_ENABLEDtrueEnable audit trail (requires persistence)
KODEMED_RETENTION_DAYS90Retention for completed sessions (days, 0=forever)
KODEMED_STORE_ORIGINALtrueStore original case data alongside changes
KODEMED_PERSISTENCE_SESSION_EXPIRY_MINUTES60Session expiry timeout (minutes)
KODEMED_PERSISTENCE_OFFLINE_TIMEOUT_MINUTES15Sessions without heartbeat expire after this (minutes)
KODEMED_HOOK_ENABLEDfalseEnable post-coding webhook
KODEMED_HOOK_URL(empty)Webhook target URL
KODEMED_HOOK_AUTH_TYPEnoneWebhook auth: none, bearer, header
KODEMED_HOOK_TIMEOUT_SECONDS30Webhook HTTP timeout (seconds)
KODEMED_HOOK_RETRY_COUNT3Webhook retry count on failure
KODEMED_HOOK_INCLUDE_RESULT_DATAfalseInclude result data in webhook payload
KODEMED_HOOK_INCLUDE_ORIGINAL_DATAfalseInclude original data in webhook payload
KODEMED_HOOK_INCLUDE_GROUPER_RESULTSfalseInclude DRG grouper results in webhook payload
KODEMED_HOOK_EVENTSappliedComma-separated event types to fire webhook on
KODEMED_RATE_LIMIT_ENABLEDtrueEnable rate limiting (DoS protection)
KODEMED_RATE_LIMIT_CAPACITY100Token bucket capacity per IP
INSTANCE_DISCONNECT_TIMEOUT60Minutes before disconnected DLL instance is terminated
HEARTBEAT_INTERVAL30WebSocket heartbeat interval (seconds)
RECONNECT_INTERVAL60DLL WebSocket reconnect interval (seconds)
KODEMED_DATASERVER_PORT8081DataServer port (used to derive internal URL)
KODEMED_UI_URL(empty)CodingUI URL for redirects (e.g. https://coding.hospital.ch)
SWAGGER_SERVER_URL(empty)Swagger UI base URL (useful behind reverse proxy)
SWAGGER_OAUTH2_CLIENT_IDkodemed-serverOAuth2 client ID for Swagger UI
TABLE_PREFIXkm_app_Database table prefix
LOGGING_LEVEL_ROOTINFORoot log level (WARN in prod profile)
MANAGEMENT_ENDPOINTShealth,info,metrics,prometheusExposed Spring Actuator endpoints

KodeMed DataServer Port 8081

Data import/export service — ICD-10, CHOP, thesaurus, hot-folder import.

Environment VariableDefaultDescription
DATASERVER_PORT / SERVER_PORT8081HTTP port (DATASERVER_PORT takes priority)
SPRING_DATASOURCE_URLjdbc:h2:mem:kodemedJDBC connection URL
SPRING_DATASOURCE_USERNAMEsaDatabase username
SPRING_DATASOURCE_PASSWORD(empty)Database password
KODEMED_AUTH_ENABLEDtrueEnable/disable OAuth2 authentication
KODEMED_ADMIN_API_KEY(empty)API key for admin endpoints (import/reimport scripts). Generate: openssl rand -hex 32
KODEMED_LICENSE_FILE(auto-search)Path to kodemed.license file
KODEMED_IMPORT_ENABLEDtrueEnable hot-folder import system
KODEMED_IMPORT_AUTO_SCANfalseAuto-scan inbox on timer (disabled by default for safety)
KODEMED_IMPORT_BASEDIR./importBase directory for import files
KODEMED_IMPORT_INBOX_DIR./import/inboxInbox — place files here for processing
KODEMED_IMPORT_SUCCESS_DIR./import/successSuccess — processed files moved here
KODEMED_IMPORT_ERROR_DIR./import/errorError — failed files moved here
KODEMED_IMPORT_SCAN_INTERVAL_MS30000Scan interval in ms (only when auto-scan=true)
KODEMED_IMPORT_BATCH_SIZE1000Batch size for data imports
KODEMED_THESAURUS_BATCH_SIZE2000Batch size for thesaurus index inserts
KODEMED_THESAURUS_AUTO_BUILDtrueAuto-build thesaurus on startup
TABLE_PREFIXkm_data_Database table prefix (different from Server!)
CORS_ALLOWED_ORIGINS(empty)CORS allowed origins
SWAGGER_SERVER_URL(empty)Swagger UI base URL
SWAGGER_OAUTH2_CLIENT_IDkodemed-serverOAuth2 client ID for Swagger UI
LOGGING_LEVEL_ROOTINFORoot log level
MANAGEMENT_ENDPOINTShealth,info,metrics,prometheus,cachesActuator endpoints (includes cache management)

KodeMed GrouperServer Port 8082

DRG grouper — stateless service for SwissDRG, TARPSY, ST Reha grouping. No database required.

Environment VariableDefaultDescription
SERVER_PORT8082HTTP port
GROUPER_AUTH_ENABLEDtrueEnable/disable auth (NOT KODEMED_AUTH_ENABLED!)
GROUPER_SPECS_PATH./specsPath to grouper specification files (.sgs)
GROUPER_CATALOGUE_PATH./cataloguesPath to catalogue files (.csv) for cost weights
GROUPER_DEFAULT_SWISSDRG15.0Default SwissDRG version
GROUPER_DEFAULT_TARPSY6.3Default TARPSY version
GROUPER_DEFAULT_STREHA3.4Default ST Reha version
KODEMED_LICENSE_FILE(auto-search)Path to kodemed.license file
CORS_ALLOWED_ORIGINS(empty)CORS allowed origins
SWAGGER_SERVER_URL(empty)Swagger UI base URL
SWAGGER_OAUTH2_CLIENT_IDkodemed-serverOAuth2 client ID for Swagger UI
LOGGING_LEVEL_ROOTINFORoot log level
LOGGING_LEVEL_COM_MIERESIT_GROUPERINFOGrouper application log level
LOGGING_LEVEL_SWISSDRGINFOSwissDRG library log level
MANAGEMENT_ENDPOINTShealth,info,metrics,prometheusActuator endpoints

KodeMed CodingUI Port 3000

React frontend served via nginx. Configured at runtime via runtime-config.js.

Config KeySourceDescription
window.__KODEMED_CONFIG__ (runtime-config.js — injected at deploy time)
apiUrlruntime-config.jsMain server API URL (e.g. https://server.hospital.ch/api/v1)
dataServerUrlruntime-config.jsDataServer URL (e.g. https://data.hospital.ch)
grouperServerUrlruntime-config.jsGrouperServer URL (reserved, UI proxies via Server)
wsUrlruntime-config.jsWebSocket URL (e.g. wss://server.hospital.ch/ws/dll)
oauth2Urlruntime-config.jsOAuth2/Keycloak base URL (e.g. https://sso.hospital.ch)
oauth2Realmruntime-config.jsOAuth2 realm name (e.g. kodemed)
oauth2ClientIdruntime-config.jsOAuth2 client ID (e.g. kodemed-ui)
URL Query Parameters (injected by DLL when opening embedded browser)
apiUrlURL paramOverride API URL
wsUrlURL paramOverride WebSocket URL
dataServerUrlURL paramOverride DataServer URL
oauth2UrlURL paramOverride OAuth2 base URL
oauth2RealmURL paramOverride OAuth2 realm
oauth2ClientIdURL paramOverride OAuth2 client ID
langURL paramUI language (de, fr, it)
classificationVersionURL paramClassification year (e.g. 2026)
Config Resolution Priority: URL params > runtime-config.js > VITE_* build vars > /api/v1/config > defaults

KodeMed DLL/Client C# Desktop

Windows desktop DLL integration. Config file: kodemed-client-config.json (next to DLL or %APPDATA%\KodeMed\).

JSON KeyDefaultDescription
serverUrl(required)KodeMed Server URL (e.g. https://kodemed.hospital.ch)
codingUIUrl(from server)CodingUI URL (fetched from /api/v1/config if not set)
oauth2Url(from server)OAuth2/Keycloak base URL
oauth2RealmkodemedOAuth2 realm name
oauth2ClientIdkodemed-dllOAuth2 client ID for desktop auth
language(system)UI language override (de, fr, it)
webSocketAutoReconnecttrueAuto-reconnect WebSocket on disconnect
webSocketReconnectIntervalSeconds60Reconnect interval (seconds, min 5)
webSocketHeartbeatIntervalSeconds30Heartbeat interval (seconds)
hook sub-object (post-coding webhook — auth credentials stored locally, NOT on server)
hook.enabled(from server)Override: enable/disable webhook
hook.url(from server)Override: webhook target URL
hook.authType(from server)Auth type: none, bearer, header
hook.authToken(local only)Bearer token for webhook auth (SENSITIVE)
hook.authHeaderName(local only)Custom header name (SENSITIVE)
hook.authHeaderValue(local only)Custom header value (SENSITIVE)

Important Notes

  • GROUPER_AUTH_ENABLED vs KODEMED_AUTH_ENABLED: GrouperServer uses its own namespace. Server and DataServer use KODEMED_AUTH_ENABLED.
  • TABLE_PREFIX: Server uses km_app_, DataServer uses km_data_. Both share the same PostgreSQL database.
  • LOGGING_LEVEL_ROOT is the correct Spring Boot env var (not LOG_LEVEL).
  • KODEMED_LICENSE_FILE: If not set, services search: ./kodemed.license, /etc/kodemed/, %APPDATA%/KodeMed/.
  • KODEMED_ENCRYPTION_KEY: Only used by Server. DataServer and GrouperServer do not encrypt data at rest.
  • Webhook auth credentials (token, header) are stored in the DLL config only, never on the server. The server only stores non-sensitive webhook settings.

Health Check & Smoke Test Endpoints

Use these public endpoints (no authentication required) to verify your deployment:

ServiceEndpointExpected Response
ServerGET /actuator/health{"status":"UP"}
ServerGET /api/v1/configJSON with serverUrl, dataServerUrl, version info
DataServerGET /actuator/health{"status":"UP"}
DataServerGET /api/v1/healthJSON with "UP" status, service name, version
GrouperServerGET /actuator/health{"status":"UP"}
GrouperServerGET /api/v1/grouper/versionsJSON with loaded grouper versions (SwissDRG, TARPSY, ST Reha)
All servicesGET /api/v1/license/statusLicense status (VALID / EXPIRED / INVALID)

HTTP 402 on any endpoint means the license is invalid or missing. Check KODEMED_LICENSE_FILE path and verify with: java -jar kodemed-license-cli.jar verify --public-key kodemed-public.pem --license kodemed.license