MyLIS-RSSA

Microbiology Laboratory Information System

---

Bahasa Indonesia

MyLIS-RSSA adalah ekosistem aplikasi Laboratory Information System untuk layanan mikrobiologi RSUD Dr. Saiful Anwar. Repo ini berisi aplikasi web/backend Laravel, aplikasi pendamping mobile/desktop Flutter, dan service listener Python untuk komunikasi alat laboratorium.

Sistem ini membantu alur kerja laboratorium mulai dari penerimaan order, registrasi sampel, pengelompokan pemeriksaan, input expertise, verifikasi hasil, pelaporan, notifikasi nilai kritis, sampai integrasi dengan SIMRS dan instrumen laboratorium.

---

Aplikasi di Dalam Repo

1. LIS Web & Backend (htdocs)

Aplikasi utama berbasis Laravel untuk operasional laboratorium. Modul ini menangani autentikasi, dashboard, pendaftaran pasien/sampel, daftar pemeriksaan, template hasil, expertise, laporan, label/barcode, logbook, biorepository, gudang BHP, API mobile, backup cloud, dan integrasi SIMRS.

Ringkasan fungsi:

• Registrasi order dari SIMRS melalui endpoint registerpasien, registerulang, dan registerjson.
• Pengelolaan pasien, dokter, poli/ruangan, user, template jawaban, dan subjawaban.
• Worklist pemeriksaan mikrobiologi berdasarkan buku/kategori sampel.
• Input dan cetak hasil pemeriksaan, adendum, label, form, dan laporan.
• Dashboard Early Warning System dan notifikasi nilai kritis.
• Modul logbook PPDS/SPV, biorepository, dan SIMBHP.
• API /api/mobile untuk aplikasi MyLIS Flutter.
• Utilitas backup/restore database ke cloud dan export/simulasi payload register API.

2. MyLIS Flutter (mylis)

Aplikasi mobile/desktop pendamping untuk akses cepat ke LIS Laravel. Aplikasi ini dipakai untuk login, cek koneksi server, dashboard, pencarian sampel, scanner barcode, Early Warning System, penerimaan pekerjaan awal, daftar pemeriksaan, detail pemeriksaan, notifikasi nilai kritis, dan pengisian expertise native.

Screen expertise yang tersedia:

• CCI
• Kultur
• Pewarna Langsung
• TBC
• Viral Load
• IgM IgG Leptospira
• PCR COVID

3. Listener Instrumen (listener)

Service Python untuk komunikasi dengan instrumen laboratorium, terutama jalur serial/TCP dan GeneXpert. Service ini membaca, memproses, dan mengirim pesan instrumen seperti ASTM/HL7, lalu menyimpan atau meneruskan data ke database LIS.

Ringkasan fungsi:

• Listener TCP untuk GeneXpert.
• Komunikasi serial untuk perangkat seperti Vitek dan BACTEC.
• Mapping kode pemeriksaan LIS ke host test code alat.
• Antrean order instrumen dan pemrosesan hasil.
• Logging harian dan log per thread untuk troubleshooting.

---

Cara Kerja Aplikasi

Alur utama sistem:

SIMRS / user web
  -> Laravel LIS menerima order dan data pasien
  -> Sampel masuk ke worklist mikrobiologi
  -> Petugas menerima, memproses, dan mengisi hasil/expertise
  -> Supervisor melakukan verifikasi atau finalisasi
  -> Hasil dicetak, dikirim, atau diekstrak kembali ke SIMRS

Alur mobile:

MyLIS Flutter
  -> login ke Laravel melalui /api/mobile/login
  -> mengambil dashboard, worklist, detail pemeriksaan, dan template expertise
  -> menyimpan draft, preliminary, final, atau kirim ke SPV
  -> Laravel menyimpan perubahan ke database LIS

Alur instrumen:

Instrumen laboratorium
  -> listener Python menerima ASTM/HL7/serial/TCP
  -> data diparse dan dicocokkan dengan order/sampel
  -> hasil atau status instrumen disimpan ke database
  -> Laravel menampilkan hasil untuk proses validasi dan pelaporan

Alur backup cloud:

Server production
  -> pg_dump database
  -> upload file .backup secara chunked ke cloud
  -> restore dapat dilakukan dengan download backup terbaru dan pg_restore

Detail backup, restore, export payload registerApi, dan simulasi kirim data SIMRS tersedia di htdocs/README.md.

---

Teknologi

• Backend: Laravel 10, PHP 8.1+ dengan platform Composer PHP 8.4.
• API & Auth: Laravel route API, token terenkripsi untuk mobile, Laravel Sanctum/Passport tersedia di dependency.
• Frontend Web: Blade, Bootstrap, jQuery, DataTables, Livewire 3, Vite.
• Database: konfigurasi .env mendukung MySQL; deployment/backup production juga memakai PostgreSQL untuk database lismikro.
• Reporting & Dokumen: TCPDF, FPDI, PhpSpreadsheet, QR/barcode generator.
• Integrasi: HL7, ASTM, serial communication, FTP, HTTP client Guzzle, bridging BPJS.
• Mobile/Desktop: Flutter, Dart, Material UI, HTTP client, shared preferences, URL launcher, mobile scanner.
• Listener Engine: Python 3, Flask, SQLAlchemy, psycopg2, pyserial, hl7.
• Runtime Ops: Artisan commands, cron backup, optional Docker Compose.

---

Instalasi LIS Web & Backend (htdocs)

Prasyarat:

• PHP 8.1 atau lebih baru.
• Composer.
• Node.js dan npm.
• Database MySQL atau PostgreSQL sesuai konfigurasi deployment.
• Ekstensi PHP yang dibutuhkan Laravel dan package proyek.

Langkah instalasi:

cd htdocs
composer install
npm install
cp .env.example .env
php artisan key:generate

Sesuaikan konfigurasi utama di .env:

APP_URL=https://lis.swandhana.test
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=db_lis
DB_USERNAME=root
DB_PASSWORD=

Jalankan migrasi bila database target memang disiapkan dari migration project:

php artisan migrate

Jalankan aplikasi lokal:

php artisan serve
npm run dev

Build aset production:

npm run build

Perintah verifikasi yang umum:

php artisan route:list
php artisan route:list --path=mobile
php -l app/Http/Controllers/MobileApiController.php

---

Instalasi MyLIS Flutter (mylis)

Prasyarat:

• Flutter SDK sesuai pubspec.yaml (Dart SDK ^3.12.2).
• Android Studio/Xcode sesuai platform target.
• Server Laravel LIS yang bisa diakses dari device atau simulator.

Langkah instalasi:

cd mylis
flutter pub get
flutter run

Jalankan dengan URL Laravel tertentu:

flutter run --dart-define=LIS_BASE_URL=https://lis.swandhana.test/

Build aplikasi:

flutter build apk --debug
flutter build ios --debug --no-codesign
flutter build macos --debug

Verifikasi:

flutter analyze
flutter test

---

Instalasi Listener Instrumen (listener)

Prasyarat:

• Python 3.
• Akses jaringan ke database LIS dan instrumen laboratorium.
• Akses port serial/TCP sesuai alat yang dipakai.

Langkah instalasi:

cd listener
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Jalankan listener utama:

python app.py

Jalankan listener GeneXpert khusus:

python geneexpert.py

Catatan konfigurasi:

• app.py dan geneexpert.py masih menyimpan mapping IP, port, perangkat, dan database di dalam file.
• Pastikan DATABASE_URL, TARGET_MAPPING, DEVICE_CONFIGS, port serial, dan port TCP sesuai lingkungan produksi.
• Default port penting: TCP GeneXpert 6001 dan HTTP trigger 6002.

---

API Mobile Utama

Prefix endpoint:

/api/mobile

Endpoint utama:

• GET /api/mobile/ping
• POST /api/mobile/login
• GET /api/mobile/dashboard
• GET /api/mobile/critical-values
• POST /api/mobile/critical-values/{id}/mark-read
• GET /api/mobile/early-warning
• GET /api/mobile/examinations/search
• GET /api/mobile/initial-work/samples
• POST /api/mobile/initial-work/samples/{id}/accept
• POST /api/mobile/initial-work/samples/{id}/reject
• GET /api/mobile/books/{master}/examinations
• GET /api/mobile/examinations/{id}
• GET /api/mobile/examinations/{id}/expertise
• POST /api/mobile/examinations/{id}/expertise/template
• POST /api/mobile/examinations/{id}/expertise

---

Manual Book

Panduan pengguna dapat diunduh melalui:

http://10.10.123.218/manual.pdf

---

Dukungan Pengembangan

Aplikasi ini dikembangkan oleh CV. Swandhana.

Alamat:

Jl. Lamandau 18A, Bunulrejo, Blimbing, Malang

Kontak WhatsApp:

081359108565

Pengembangan juga didukung oleh kolaborasi antara pengembang dan AI assistant seperti ChatGPT/Gemini untuk dokumentasi, refactoring, dan percepatan pekerjaan teknis.

---

Lisensi

Proyek ini menggunakan lisensi MIT. Lihat file LICENSE jika tersedia di distribusi project.

---

English Version

MyLIS-RSSA is a Laboratory Information System ecosystem for the microbiology service at RSUD Dr. Saiful Anwar. This repository contains a Laravel web/backend application, a Flutter mobile/desktop companion app, and a Python listener service for laboratory instrument communication.

The system supports laboratory workflows from order intake, sample registration, examination grouping, expertise entry, result verification, reporting, critical value notification, to SIMRS and instrument integration.

---

Applications in This Repository

1. LIS Web & Backend (htdocs)

The main Laravel application for laboratory operations. It handles authentication, dashboards, patient/sample registration, examination lists, result templates, expertise, reports, labels/barcodes, logbooks, biorepository, BHP inventory, mobile APIs, cloud backup, and SIMRS integration.

Main capabilities:

• Order registration from SIMRS through registerpasien, registerulang, and registerjson.
• Management of patients, doctors, clinics/rooms, users, answer templates, and sub-answers.
• Microbiology worklists grouped by sample book/category.
• Result entry, result printing, addendum, labels, forms, and reports.
• Early Warning System dashboard and critical value notifications.
• PPDS/SPV logbook, biorepository, and SIMBHP modules.
• /api/mobile endpoints for the MyLIS Flutter app.
• Cloud database backup/restore and register API payload export/simulation utilities.

2. MyLIS Flutter (mylis)

A mobile/desktop companion app for fast access to the Laravel LIS. It supports login, server ping, dashboard, sample search, barcode scanning, Early Warning System, initial work acceptance, examination lists, examination details, critical value notifications, and native expertise entry.

Available expertise screens:

• CCI
• Kultur
• Pewarna Langsung
• TBC
• Viral Load
• IgM IgG Leptospira
• PCR COVID

3. Instrument Listener (listener)

A Python service for laboratory instrument communication, especially serial/TCP and GeneXpert workflows. It receives, processes, and sends instrument messages such as ASTM/HL7, then stores or forwards the data to the LIS database.

Main capabilities:

• TCP listener for GeneXpert.
• Serial communication for devices such as Vitek and BACTEC.
• Mapping from LIS examination names to instrument host test codes.
• Instrument order queue and result processing.
• Daily logs and per-thread logs for troubleshooting.

---

How the System Works

Main workflow:

SIMRS / web user
  -> Laravel LIS receives orders and patient data
  -> samples enter the microbiology worklist
  -> staff accept, process, and enter results/expertise
  -> supervisor verifies or finalizes the result
  -> result is printed, sent, or extracted back to SIMRS

Mobile workflow:

MyLIS Flutter
  -> logs in to Laravel through /api/mobile/login
  -> fetches dashboard, worklist, examination details, and expertise templates
  -> saves draft, preliminary, final, or sends to SPV
  -> Laravel persists the changes to the LIS database

Instrument workflow:

Laboratory instrument
  -> Python listener receives ASTM/HL7/serial/TCP messages
  -> data is parsed and matched with orders/samples
  -> instrument results or statuses are stored in the database
  -> Laravel displays the result for validation and reporting

Cloud backup workflow:

Production server
  -> pg_dump database
  -> uploads .backup file to cloud in chunks
  -> restore can download the latest backup and run pg_restore

Detailed backup, restore, registerApi payload export, and SIMRS payload simulation notes are available in htdocs/README.md.

---

Technology Stack

• Backend: Laravel 10, PHP 8.1+ with Composer platform PHP 8.4.
• API & Auth: Laravel API routes, encrypted token for mobile, Laravel Sanctum/Passport available in dependencies.
• Web Frontend: Blade, Bootstrap, jQuery, DataTables, Livewire 3, Vite.
• Database: .env supports MySQL; production/backup deployment also uses PostgreSQL for the lismikro database.
• Reporting & Documents: TCPDF, FPDI, PhpSpreadsheet, QR/barcode generator.
• Integrations: HL7, ASTM, serial communication, FTP, Guzzle HTTP client, BPJS bridging.
• Mobile/Desktop: Flutter, Dart, Material UI, HTTP client, shared preferences, URL launcher, mobile scanner.
• Listener Engine: Python 3, Flask, SQLAlchemy, psycopg2, pyserial, hl7.
• Runtime Ops: Artisan commands, cron backup, optional Docker Compose.

---

Installing LIS Web & Backend (htdocs)

Requirements:

• PHP 8.1 or newer.
• Composer.
• Node.js and npm.
• MySQL or PostgreSQL database depending on the target deployment.
• PHP extensions required by Laravel and this project's packages.

Installation:

cd htdocs
composer install
npm install
cp .env.example .env
php artisan key:generate

Adjust the main .env configuration:

APP_URL=https://lis.swandhana.test
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=db_lis
DB_USERNAME=root
DB_PASSWORD=

Run migrations when the target database is meant to be prepared from this project's migrations:

php artisan migrate

Run locally:

php artisan serve
npm run dev

Build production assets:

npm run build

Common verification commands:

php artisan route:list
php artisan route:list --path=mobile
php -l app/Http/Controllers/MobileApiController.php

---

Installing MyLIS Flutter (mylis)

Requirements:

• Flutter SDK matching pubspec.yaml (Dart SDK ^3.12.2).
• Android Studio/Xcode depending on the target platform.
• A Laravel LIS server reachable from the device or simulator.

Installation:

cd mylis
flutter pub get
flutter run

Run with a specific Laravel URL:

flutter run --dart-define=LIS_BASE_URL=https://lis.swandhana.test/

Build:

flutter build apk --debug
flutter build ios --debug --no-codesign
flutter build macos --debug

Verification:

flutter analyze
flutter test

---

Installing Instrument Listener (listener)

Requirements:

• Python 3.
• Network access to the LIS database and laboratory instruments.
• Serial/TCP port access according to the target instruments.

Installation:

cd listener
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the main listener:

python app.py

Run the dedicated GeneXpert listener:

python geneexpert.py

Configuration notes:

• app.py and geneexpert.py still keep IP, port, device, and database mapping inside the files.
• Make sure DATABASE_URL, TARGET_MAPPING, DEVICE_CONFIGS, serial ports, and TCP ports match the production environment.
• Important default ports: GeneXpert TCP 6001 and HTTP trigger 6002.

---

Main Mobile API

Endpoint prefix:

/api/mobile

Main endpoints:

• GET /api/mobile/ping
• POST /api/mobile/login
• GET /api/mobile/dashboard
• GET /api/mobile/critical-values
• POST /api/mobile/critical-values/{id}/mark-read
• GET /api/mobile/early-warning
• GET /api/mobile/examinations/search
• GET /api/mobile/initial-work/samples
• POST /api/mobile/initial-work/samples/{id}/accept
• POST /api/mobile/initial-work/samples/{id}/reject
• GET /api/mobile/books/{master}/examinations
• GET /api/mobile/examinations/{id}
• GET /api/mobile/examinations/{id}/expertise
• POST /api/mobile/examinations/{id}/expertise/template
• POST /api/mobile/examinations/{id}/expertise

---

Manual Book

User manual:

http://10.10.123.218/manual.pdf

---

Development Support

This application is developed by CV. Swandhana.

Address:

Jl. Lamandau 18A, Bunulrejo, Blimbing, Malang

WhatsApp:

081359108565

Development is also supported by collaboration between developers and AI assistants such as ChatGPT/Gemini for documentation, refactoring, and technical acceleration.

---

License

This project uses the MIT license. See the LICENSE file if it is available in the project distribution.