Felicity LIMS

The Next Generation Open Source Laboratory Information Management System (LIMS)

---

Overview

Felicity LIMS is an open-source Laboratory Information Management System designed to streamline laboratory workflows in clinical and medical environments. It empowers laboratories to accurately manage sample lifecycles, metadata, and experimental data while ensuring compliance and efficiency.

Felicity strives to promote an accurate flow of sample and associated experimental data to and through a laboratory to produce information that is used to make conclusions and critical decisions.

Felicity LIMS will ensure that sufficient metadata is captured and clinical laboratory personnel can track the lifecycle of a bio-specimen in the laboratory from receipt to dispatch.

Felicity is the quality of being good, pleasant, or desirable.

Key Features

• Comprehensive Workflow Management: Track samples from receipt to dispatch.
• Real-Time Analytics: Interactive dashboards for actionable insights.
• Data Integrity: Metadata tracking to ensure reliability in decision-making.
• User Management: Role-based access control (RBAC) and user profiles.
• Scalability: Modular architecture supporting integration with emerging technologies.

---

Technology Stack

Frontend

• Framework: Vite, Vue.js
• Styling: Tailwind CSS
• State Management: URQL

Backend

• Framework: FastAPI, Strawberry GraphQL
• Database: PostgreSQL (main DB), MongoDB (audit logs, etc)
• Storage: MinIO (object storage for reports, etc)
• Caching: Dragonfly Redis (locks, WebSocket subscriptions)

---

Modules

• Dashboard: Analytics and performance tracking.
• Patient Management: Listings, details, audit logs, and search capabilities.
• Sample Management: Lifecycle tracking, worksheets, reports, and audit trails.
• Inventory: Transactions, adjustments, orders, and requests.
• Shipments: FHIR-ready functionality, listing, and details.
• Storage: Management of storerooms, containers, and templates.
• User & Client Management: Listings, profiles, and contact details.
• Admin Tools: Advanced administrative controls and reflex rules.
• Billing (in development): Profiles and RBAC integration.

---

Development setup (docker)

git clone https://github.com/beak-insights/felicity-lims.git
cd felicity-lims
# build and run
docker compose -f docker-compose.dev.yml up -d --build
# database setup 
docker compose -f docker-compose.dev.yml exec felicity-api felicity-lims db upgrade

Production Installation

Using Docker (Recommended)

Felicity LIMS can be quickly deployed using Docker Compose.

Step 1: Clone the Repository

git clone https://github.com/beak-insights/felicity-lims.git
cd felicity-lims
docker compose -f docker-compose.dev.yml up -d <preset> --build

Step 2: Choose a Preset

Choose between FastAPI serving static files or using Nginx/Caddy as a reverse proxy.

Preset Examples:

• felicity-aio: FastAPI for API and static files without a reverse proxy.
• felicity-aio-nginx: FastAPI for API and static files and Nginx as a reverse proxy in front.
• felicity-aio-caddy: FastAPI for API and static files and Caddy as a reverse proxy in front.
• felicity-static-nginx: FastAPI for API, Nginx for static files.
• felicity-static-caddy: FastAPI for API, Caddy for static files.

---

Step 3: Deploy

docker compose -f docker-compose.yml up -d <preset> --build
docker compose -f docker-compose.yml exec <preset> bash -c "felicity-lims upgrade"
docker compose -f docker-compose.yml logs <preset> -f -n100

Manual Installation (Alternative)

For environments where Docker is not an option:

1. Install OS Requirements:

   sudo apt update && apt install libcairo2-dev pkg-config python3-dev gcc g++
   

2. Setup Python Virtual Environment:

   conda create -n felicity python=3.11
   conda activate felicity
   

3. Install Dependencies:

   pip install -r requirements.txt
   

4. Build the Frontend:

   pnpm install
   pnpm standalone:build
   

5. Run the Backend:

   pnpm server:gu
   

For production, use Supervisor to demonize processes as follows:

1. Install supervisor

   sudo systemctl status supervisor
   

2. create supervisor config file

   sudo nano /etc/supervisor/conf.d/felicity_lims.conf
   

3. Copy and Paste the following and edit correct accordingly

   command=/home/<user>/miniconda3/bin/python <full path to felicity lims root folder>
   autostart=true
   autorestart=true
   stderr_logfile=/var/log/felicity_lims.err.log
   stdout_logfile=/var/log/felicity_lims.out.log
   

4. Inform supervisor of our new programs:

   sudo supervisorctl update
   sudo supervisorctl reload
   

5. Tail Error logs:

   tail -f /var/log/felicity_lims.err.log
   

6. Tail output logs:

   tail -f /var/log/felicity_lims.out.log
   

---

Application Monitoring

Felicity LIMS integrates OpenTelemetry for application performance monitoring.

1. Enable Tracing:

   export RUN_OPEN_TRACING=True
   opentelemetry-bootstrap --action=install
   

2. Deploy SigNoz (Recommended for Metrics):

   git clone -b main https://github.com/SigNoz/signoz.git
   cd signoz/deploy/
   docker-compose -f docker/clickhouse-setup/docker-compose.yaml up -d
   

Access the SigNoz dashboard at http://localhost:3301.

---

Performance Testing

Evaluate system performance using Locust or other load-testing tools. We recommend testing concurrency to simulate real-world scenarios.

---

Contributing

We welcome contributions from the community!

• Follow the contribution guide in the repository.
• Ensure all code adheres to the project's linting and testing standards.

---

Contact

• Email: aurthurmusendame@gmail.com
• LinkedIn: Aurthur Musendame
• WhatsApp: Chat with us
• Telegram: Join the discussion

---