Lift Nexus API

Spring Boot backend MVP for warehouse dispatch optimization.
Built to explore domain modeling, async job handling, PostgreSQL/Flyway persistence, integration testing, and Timefold-based constraint solving.

Read the docs » · ▶ 5-minute demo » · Getting started · Roadmap

---

Status: Portfolio / learning project. The current focus is a static dispatching MVP, not a production warehouse management system.

About

Lift Nexus API models a simplified warehouse dispatching scenario where transport orders need to be assigned to forklifts.

The project goes beyond a basic CRUD API by combining:

• a warehouse domain model for forklifts, load units, storage bins, and transport orders
• asynchronous optimization jobs with status tracking
• Timefold Solver for constraint-based assignment planning
• PostgreSQL persistence with Flyway migrations
• OpenAPI documentation and Docker-based local setup
• unit and integration tests with JUnit 5 and Testcontainers

The goal is to experiment with backend architecture and optimization in a realistic intralogistics domain.

Read the full documentation

Tech Stack

Features

• Manage forklifts, load units, storage bins, and transport orders through REST endpoints
• Start dispatch optimization as an asynchronous job
• Poll job status and retrieve optimization results
• Apply initial hard and soft constraints for forklift-to-order assignment planning
• Run locally with Docker Compose
• Validate database changes through Flyway migrations
• Generate and inspect API documentation through Swagger UI

Demo

This demo shows the v0.1.0 workflow running locally with Docker Compose and Postman: seeded warehouse data, a submitted dispatch job, and the final solver result.

For the full walkthrough, see the Demo documentation.

Getting Started

Prerequisites

For the recommended setup:

docker --version
docker compose version

For local development without running the app container:

java -version
./mvnw -version

Run with Docker Compose

git clone https://github.com/v1rex/lift-nexus-api.git
cd lift-nexus-api
docker compose up -d

The API should be available at:

• Swagger UI: http://localhost:8080/swagger-ui.html
• Hosted docs: https://lift-nexus.amine-bahij.dev/

Stop the environment:

docker compose down

Development Mode

Run PostgreSQL in Docker and start the application from your IDE or terminal:

docker compose up -d db
./mvnw clean spring-boot:run

Testing and Code Quality

./mvnw clean test            # Unit tests
./mvnw clean verify          # Full verification, including integration tests
./mvnw spotless:check        # Formatting check
./mvnw spotless:apply        # Apply formatting

Coverage report:

open target/site/jacoco/index.html

Documentation

The full project documentation is available here:

lift-nexus.amine-bahij.dev

It includes the project overview, architecture, domain model, optimization approach, API usage, testing strategy, known limitations, and roadmap.

For release notes, see CHANGELOG.md.

Current Scope and Limitations

Lift Nexus API is an MVP / portfolio project, not a production warehouse management system yet.

Main limitations:

• No authentication or authorization yet
• Simplified warehouse topology and pathfinding
• Limited solver constraints
• Basic observability only
• Not tested in a production-like deployment environment yet

See the full documentation for detailed limitations and planned improvements.

Roadmap

Milestone	Status	Focus
Core MVP - Static Dispatching	Released in v0.1.0	Physical warehouse model and one-shot optimization
Dynamic Dispatching	Planned	React to warehouse changes instead of running only one-shot dispatching
Production Constraints	Planned	Add more realistic planning constraints such as deadlines, priorities, equipment compatibility, and energy-aware dispatching
Auth, Monitoring, Deployment	Planned	Improve security, observability, and deployment readiness
Performance/Benchmarking	Planned	Measure behavior under larger scenarios

See the open issues and the project roadmap for more details.

What I Learned

I built this project to go beyond simple CRUD applications and practice backend architecture in a more realistic optimization-driven domain.

Coming from an academic optimization background, where I previously worked with mathematical modeling in GurobiPy, this project helped me understand how optimization can be integrated into a real backend application using Timefold.

Through this project, I learned and applied:

• domain modeling for warehouse dispatching
• asynchronous job handling
• database migrations with Flyway
• integration testing with PostgreSQL and Testcontainers
• separating API, service, persistence, and planning concerns
• constraint solving with Timefold
• documenting architectural trade-offs and limitations

For more context, read my article: Why I am building Lift Nexus API.

License

Distributed under the Apache License 2.0. See LICENSE for more information.

Copyright 2026 Mohamed Amine Bahij

Contact

Amine Bahij

• GitHub: @v1rex
• Email: contact@amine-bahij.dev
• Project: https://github.com/v1rex/lift-nexus-api

Acknowledgments

• Timefold – Constraint solver
• Spring Boot – Java application framework
• PostgreSQL – Relational database
• Flyway – Database migrations