MOLS is a logistics app to manage warehouses, resources, stock, orders and shipments, with an audit log (movements) so you can trace what changed and why.
🔗 Live demo: mols-demo.onrender.com/app, log in with a read-only auditor account: AuditorDemo / DemoPassword77 (see HELP.md for what each role can do). First load may take up to a minute, since this runs on free-tier hosting that sleeps when idle.
- Append-only audit trail: every stock change automatically records a Movement
(
ENTRY/EXIT) with the acting user; movements can never be edited or deleted - Status state machines: order and shipment lifecycles are enforced enums
(e.g. a
DELIVEREDshipment orCOMPLETEDorder can never be reverted) - Concurrency-safe stock: optimistic locking detects simultaneous adjustments (HTTP 409) instead of silently losing updates
- Database-level integrity: CHECK/UNIQUE/NOT NULL constraints and FK indexes managed by Flyway migrations
- Hardened login: temporary lockout after repeated failures, security event logging, 12+ character password policy
- Orders with items (create/edit, inline item management)
- Shipments carry specific order items/quantities; delivering one shipment fulfills only its
own items, so an order can be
PARTIALLY_SHIPPEDacross several shipments beforeCOMPLETED - Traceability views (Order/Shipment details show linked movements)
- Dashboard with KPIs, charts, a live logistics map, recent activity and alerts
- First-run setup to create the initial admin user
- Admin-only user management (roles, password reset, enable/disable)
Resumen en español (🇪🇸)
MOLS es un sistema web para gestionar stock, pedidos y envíos, con auditoría de movimientos para trazabilidad.
Para detalles técnicos y arquitectura, consulta PROJECT_OVERVIEW.md.
- Java 21, Spring Boot 4 (Spring MVC)
- PostgreSQL + Spring Data JPA (Hibernate,
validatemode) - Flyway (versioned database migrations)
- Testcontainers (end-to-end integration tests on a real PostgreSQL)
- CI: GitHub Actions with JaCoCo coverage gate, CodeQL, OWASP Dependency-Check, CycloneDX SBOM and Dependabot
- Spring Security (JWT for API, delivered as an HttpOnly cookie for the browser SPA)
- React 19 + TypeScript + Vite + Tailwind 4 (the SPA at
/app) - OpenAPI/Swagger (springdoc)
- Docker + Docker Compose
With the application running:
- App: http://localhost:8080/app
- First-run setup (only shown until the first admin exists): http://localhost:8080/app/setup
- Swagger UI: http://localhost:8080/swagger-ui.html
The dashboard shows sensible empty states on a fresh database, and becomes more useful as you build history.
Includes:
- KPI cards: total orders (with pending), stock quantity across warehouses, active shipments, low-stock alerts, recent movements (24h), fulfillment rate
- Charts: stock distribution by warehouse (bar), movements by type (donut), orders by status (donut)
- A live logistics map (warehouse/unit pins, animated shipment routes)
- Alerts: low stock items (link to adjust), stale pending orders (link to order detail)
Dashboard thresholds live in src/main/resources/application.properties:
mols.dashboard.low-stock-threshold(default: 10)mols.dashboard.critical-stock-threshold(default: 5)mols.dashboard.stale-order-days(default: 3)mols.dashboard.recent-activity-hours(default: 24)mols.dashboard.movement-chart-days(default: 30)mols.dashboard.fulfillment-target-percent(default: 90)
- Technical details: PROJECT_OVERVIEW.md
- Local run / troubleshooting: HELP.md
./mvnw.cmd spring-boot:runOr with Docker (first time only, .env is gitignored so you need your own):
cp .env.example .env
# then edit .env and set SECURITY_JWT_SECRET_KEY (generate with: openssl rand -hex 32)
docker compose up --build -dThis project is for educational and portfolio purposes.
PRs are welcome.
- Keep changes small and focused
- Add/adjust tests when behavior changes
- Prefer service-layer rules (controllers stay thin)