LabGraph-API: Advanced Internal Laboratory Quality Control System

Technologies

Overview

LabGraph-API is a comprehensive RESTful API designed to revolutionize internal quality control processes in clinical and research laboratories. Built with modern technologies and best practices, this system helps laboratories monitor, analyze, and ensure the reliability of their analytical processes through robust statistical analysis and intuitive data visualization.

Key Features

• Comprehensive Control Standard Management: Track and manage control materials with detailed metadata
• Statistical Analysis Engine: Perform Westgard rule evaluations, trend analysis, and variance monitoring
• Multi-level User Management: Role-based access control with customizable permissions
• Real-time Monitoring: Get instant alerts when quality issues are detected
• Interactive Data Visualization: View quality metrics through intuitive charts and graphs
• Audit Trail: Complete history of all quality control activities
• Scalable Architecture: Designed to handle laboratories of any size

Architecture

LabGraph-API follows a modular architecture:

├── .github/workflows      # GitHub Actions workflow configurations
├── src/
│   ├── main/
│   │   ├── java/leonardo/labutilities/qualitylabpro/
│   │   │   ├── ControlApplication.java
│   │   │   ├── configs/            # Application configurations
│   │   │   │   ├── constants/     # System constants
│   │   │   │   ├── database/      # Database configurations
│   │   │   │   ├── date/          # Date/time configurations
│   │   │   │   ├── docs/          # API documentation
│   │   │   │   ├── rest/          # REST configurations 
│   │   │   │   └── security/      # Security settings
│   │   │   └── domains/           # Domain-driven modules
│   │   │       ├── analytics/     # Analytics domain
│   │   │       │   ├── controllers/
│   │   │       │   ├── dtos/
│   │   │       │   ├── models/
│   │   │       │   ├── repositories/
│   │   │       │   └── services/
│   │   │       ├── shared/        # Shared components
│   │   │       │   ├── enums/
│   │   │       │   ├── exceptions/
│   │   │       │   └── utils/
│   │   │       └── users/         # User management domain
│   │   │           ├── controllers/
│   │   │           ├── dtos/
│   │   │           ├── models/
│   │   │           ├── repositories/
│   │   │           └── services/
│   │   └── resources/
│   │       ├── db/migration/     # Flyway migrations
│   │       └── application.properties
│   └── test/
│       └── java/                # Test classes
├── database/                    # Database scripts
├── docker/                      # Docker configurations
│   ├── dev/                    # Development environment
│   └── prod/                   # Production environment
├── nginx/                      # Nginx configurations
├── docker-compose.yml          # Docker compose files
└── pom.xml                     # Maven configuration

Architectural Highlights

• configs/: Configuration classes organized by purpose
  • constants/: System-wide constants
  • database/: Database configurations
  • security/: Security settings and configurations
• domains/: Domain modules
  • analytics/: Analytics domain components
  • shared/: Cross-cutting concerns and utilities
  • users/: User management domain
• Each domain contains:
  • controllers/: REST endpoints
  • dtos/: Data Transfer Objects
  • models/: Domain entities and components
  • repositories/: Data access layer
  • services/: Business logic
• docker/: Environment-specific Docker configurations

Getting Started

Prerequisites

• Java 21
• MariaDB 11.2
• Maven
• Docker
• Git

Installation Options

Option 1: Docker Development Environment (Recommended)

This method provides a complete development environment with live reload capabilities.

1. Clone the repository

   git clone https://github.com/LabGraphTeam/LabGraph-Back-End.git
   cd LabGraph-Back-End

2. Configure environment variables

   DB_USER=root
   DB_ROOT_PASSWORD=root
   DB_DATABASE=lab_api_alpha
   DB_DATABASE_TEST=lab_api_test
   DB_LOCAL_PORT=3306
   DB_DOCKER_PORT=3306
   SPRING_DATASOURCE_URL=jdbc:mariadb://localhost:3306/lab_api_test
   API_SECURITY_TOKEN_SECRET=your_secret_token_here_123456789
   API_SECURITY_ISSUER=example-api-issuer
   SERVER_LOCAL_PORT=8080
   SERVER_DOCKER_PORT=8080
   [email protected]
   SPRING_MAIL_PASSWORD=examplePassword123!
   [email protected]

   cp .env.example .env
   # Edit .env with your preferred settings

3. Start the development stack

   docker compose --profile dev up --build

   This will start:

   • MariaDB database (accessible at localhost:3306)
   • Spring Boot application with live reload (accessible at localhost:8080)

Option 2: Local Maven Execution

For development without Docker:

1. Clone and configure

   git clone https://github.com/LabGraphTeam/LabGraph-Back-End.git
   cd LabGraph-Back-End
   cp .env.example .env
   # Edit .env with your preferred settings

2. Run with Maven

   ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

   Note: You'll need to have a MariaDB instance running separately.

Option 3: Production-like Environment

To test in a production-like environment:

docker compose --profile prod up --build

This starts a fully optimized stack with Nginx as reverse proxy.

Development Workflow

Live Reload

The development environment supports hot-reloading:

• Source code is mounted as a volume in the container
• Changes to Java files trigger automatic recompilation
• Application restarts automatically with changes

API Documentation

Swagger UI is available at:

http://localhost:8080/swagger-ui.html

Use this interface to explore endpoints, models, and test API calls directly.

Database Management

The database is accessible at:

• Host: localhost
• Port: 3306
• Credentials: As configured in your .env file

Database migrations are managed through Flyway and run automatically on startup.

Testing

Running Unit Tests

# Standard test execution
./mvnw test

# With detailed logging
./mvnw test -Dorg.slf4j.simpleLogger.defaultLogLevel=DEBUG

# With extra debugging information
./mvnw test -X

Integration Tests

./mvnw verify

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and delivery:

1. Build & Test: Runs on every pull request and push to main
2. Code Quality: Static analysis with SonarQube
3. Docker Build: Creates optimized Docker images
4. Deployment: Automatic deployment to staging/production environments

Details are available in the .github/workflows directory.

Front-end Integration

LabGraph includes a React-based front-end with Recharts.js for visualization:

The front-end repository is available at LabGraphTeam/LabGraph-Front-End.

Contributing

We welcome contributions from the community! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Implement your changes
4. Run tests

   ./mvnw test

5. Commit your changes

   git commit -m "Add your detailed commit message"

6. Push to your fork

   git push origin feature/your-feature-name

7. Open a pull request

Contribution Guidelines

• Follow the existing code style
• Write unit tests for new features
• Update documentation for API changes
• Reference any related issues in your PR

Deployment

Environment Configuration

Production deployments should include:

• Proper database credentials in .env
• Configured SSL certificates for HTTPS
• Adjusted memory limits for JVM
• Database backup strategy

Docker Deployment

 # Pull the latest image
docker pull leonardomeireles55/quality-lab-pro-back-end:latest

# Run with your environment variables
docker run -d -p 8080:8080 --env-file .env leonardomeireles55/quality-lab-pro-back-end:latest

Cloud Hosting

LabGraph is optimized for deployment on DigitalOcean:

Support

For questions, issues, or support:

• Open an issue on GitHub
• Contact the development team at [email protected]

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details.

The GPL-3.0 ensures that:

• The software remains open source
• Any modifications or derived works must also be released under GPL-3.0
• Source code must be made available when distributing the software

---

© 2025 LabGraph Team. All rights reserved.