Clínica Management System for a Healthcare Provider
Microservices platform for a Colombian healthcare provider, from admission to claim objection. It began as a hobby with the same code copied across nine services; I rebuilt it to the real health-billing rules.
- Stack
- Java 21 · Spring · Kafka · OpenBao · PostgreSQL · MySQL · Docker
- Status
- Completed
- Year
- 2025
- Code
- GitHub ↗DeepWiki ↗
Real output of the tests against the whole system (37 containers), with the DIAN and the Ministry simulated. Long waits are compressed. The output is in Spanish, like the system.
What’s happening
- 01Staff with second factor
- 02Contract with the insurer
- 03Patient and episode
- 04Clinical record
- 05Fiscal setup
- 06Signed invoice and DIAN
- 07RIPS and filing
- 08Objection and credit note
- 09Public verification
- 10Events via Debezium
- 11Access rules
- 01patient-service goes down
- 02Clinical record keeps going
- 03A new patient, 503
- 04patient-service returns
- 05All healthy
- 01The active node goes down
- 02Another node takes over
- 03Secrets still readable
- 04A service still starts
- 05The node returns
- 06It rejoins on its own
- 01All three nodes go down
- 02Patients still register
- 03Sealed records still verify
- 04Sealing something new, 503
- 05OpenBao returns
- 06It recovers on its own
The interactive piece for this case lives at ymid.me/en/projects/clinica/
From hobby to a system for real clinics
Clínica grew out of CRUD-Test, my first backend, and out of my job at a clinic. The first version was a hobby: nine layered services, each one validating the JWT with the same copied code, lots of repeated code and some that nobody used.
Once I saw the project was mostly the same code pasted into several services, I decided to do it properly: I rebuilt it with Claude's help and to Colombian regulations, so it solves a real problem for clinics in the country.
The hardest part was the size
Every service turned out to be a project of its own: the clinical record signs notes and encrypts attachments, billing talks to the DIAN (the tax authority) and the Ministry of Health. Today it's ten services and more than a thousand Java files. Seven moved to hexagonal architecture, and what used to be copied now lives in four shared libraries.
If something goes down, care goes on
You can see it above in the real tests, by taking down the patient service or OpenBao. The same principle applies across the system:
- The emergency room doesn't wait for a contract. If contracting doesn't answer, the ER admits anyway, because the law requires it, and billing reviews the coverage later.
- No event is lost. Each service stores its events in its own database, in the same transaction as the change, and Debezium publishes them to Kafka. If Kafka is down, they wait there.
- Billing doesn't wait for anyone. The invoice is issued even if OpenBao or the DIAN don't answer; signing and delivery retry on their own.
Security for health data
- No key leaves OpenBao. In the old version, the token signing key ended up published in the repository; now tokens, invoices and receipts are signed with keys that can't be exported.
- Every service applies the person's permissions. The browser never sees a token, and when one service calls another it does so with the permissions of whoever asked, not those of a technical user.
- The application can't delete. Its database user can't delete clinical data or invoices, or change the schema, and changes are audited.
Billing the way the rules require
This is the part I know from work, and the one the test above walks through. Billing follows the real cycle: health-sector electronic invoice, DIAN validation, RIPS report to the Ministry, filing with the insurer within 22 business days, and answering claim objections with the official manual. An assistant running a local AI model reviews invoices without the data leaving the clinic, and it only proposes actions that a person confirms.
The frontend is still just the project's base, and the system isn't certified with the DIAN: the tests run against simulators.