Order Management System - FHL Logistics

👨‍💻 Coder Information

• Name: Luis Martinez
• Clan: NodeJS/NestJS

Project Description

REST API built with Node.js, Express, TypeScript, JWT, and Sequelize (PostgreSQL) for managing delivery orders for FHL logistics company. The system handles the complete lifecycle of delivery orders, from client registration to order tracking and warehouse management.

Technologies Used

• Node.js (v18+)
• TypeScript
• Express.js - Web framework
• PostgreSQL - Relational database
• Sequelize - ORM
• JWT - Authentication
• Bcrypt - Password hashing
• Swagger - API documentation
• Nodemon - Development server

Features

Authentication System

• User registration with two roles: administrator and analyst
• JWT-based authentication
• Protected routes based on user roles

User Roles & Permissions

Administrator

• Full CRUD operations on clients, warehouses, products, and orders
• Can activate/deactivate warehouses
• Complete order management

Analyst

• View orders
• Update order status (pending, in_transit, delivered)
• Read-only access to other resources

Modules

Client Management

• Register clients with ID card, name, email, and delivery address
• List all clients
• Search client by ID card
• Prevent duplicate ID card registration

Warehouse Management

• Activate/deactivate warehouses
• List active warehouses with stock information
• Manage warehouse inventory

Product Management

• CRUD operations for products
• Search products by code
• Logical deletion (soft delete)
• Stock management per warehouse

Order Management

• Create orders with products from specific warehouses
• Validate stock availability before order creation
• Update order status
• Track order history
• Filter orders by client

Prerequisites

• Node.js >= 18.x
• PostgreSQL >= 12.x
• npm or yarn

Installation

1. Clone the repository

git clone <repository-url>
cd "Order Management System"

2. Install dependencies

npm install

3. Configure environment variables

Create a .env file in the root directory based on .env.example:

# PostgreSQL Configuration
PGHOST=localhost
PGPORT=5432
PGDATABASE=deliverydb
PGUSER=postgres
PGPASSWORD=your_secure_password_here

# MongoDB Configuration (optional)
MONGO_URI=mongodb://localhost:27017/deliverydb

# JWT Configuration
JWT_SECRET=change_this_to_a_super_secure_secret_in_production
JWT_EXPIRES_IN=24h

# Server Configuration
PORT=3001

4. Create the database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE deliverydb;

# Exit psql
\q

5. Install dependencies

After configuring the environment, install the required packages:

npm install

6. Run database seeders

Populate the database with initial data (users, clients, warehouses, products):

npm run seed

This will create:

• 2 users (admin and analyst)
• 5 test clients
• 4 warehouses
• 10 products with stock distribution

7. Start the application

Development mode

npm run start

The API will be available at: http://localhost:3001

Important: Make sure PostgreSQL is running before starting the application.

---

🐳 Docker Deployment (Alternative)

Quick Start with Docker

If you prefer to use Docker, you can deploy the entire stack with one command:

# Copy Docker environment file
cp .env.docker .env

# Start all services (PostgreSQL, MongoDB, API)
docker compose up -d

# Run seeders
docker compose exec api npm run seed:force

# View logs
docker compose logs -f api

The API will be available at: http://localhost:3001

Docker Services

• PostgreSQL - Database (port 5432)
• MongoDB - Logs (port 27017)
• API - Node.js application (port 3001)

Useful Docker Commands

# Stop all services
docker compose down

# Restart API only
docker compose restart api

# View all containers
docker compose ps

# Access API container
docker compose exec api sh

For complete Docker documentation, see DOCKER_GUIDE.md

---

API Documentation

Swagger UI

Once the server is running, access the interactive Swagger documentation at:

http://localhost:3001/api-docs

Postman Collection

A complete Postman collection is available in the postman/ directory:

• FHL_Order_Management_System.postman_collection.json - Complete API collection
• FHL_Environment.postman_environment.json - Environment variables

How to Use Postman Collection:

1. Import both files into Postman
2. Select the "FHL Order Management - Local" environment
3. Run "Login Admin" or "Login Analyst" to get authentication tokens
4. Tokens are automatically saved and used in subsequent requests

See postman/README.md for detailed instructions.

Database Structure

Main Tables

• users - System users (admin, analyst)
• clients - Delivery clients
• warehouses - Storage facilities
• products - Product catalog
• warehouse_products - Stock per warehouse
• orders - Delivery orders
• order_items - Products in each order

Relationships

• Orders belong to Clients
• Orders contain multiple OrderItems
• OrderItems reference Products and Warehouses
• Products have stock in multiple Warehouses (through warehouse_products)

API Endpoints

Authentication

• POST /auth/register - Register new user
• POST /auth/login - User login

Clients (Protected - Admin/Analyst)

• GET /clients - List all clients
• POST /clients/search - Search client by ID card
• PUT /clients/:id - Update client (Admin only)
• DELETE /clients/:id - Delete client (Admin only)

Warehouses (Protected - Admin/Analyst)

• GET /warehouses/active - List active warehouses with stock
• PUT /warehouses/:id/activate - Activate warehouse (Admin only)
• PUT /warehouses/:id/deactivate - Deactivate warehouse (Admin only)

Products

• GET /products - List all active products (Public)
• GET /products/:id - Get product by ID (Public)
• GET /products/code/:code - Get product by code (Public)
• POST /products - Create product (Admin only)
• PUT /products/:id - Update product (Admin only)
• DELETE /products/:id - Logical delete product (Admin only)

Orders (Protected)

• GET /orders - List orders (filtered by role)
• GET /orders/history - Get complete order history
• GET /orders/:id - Get order by ID
• POST /orders - Create new order
• PUT /orders/:id/status - Update order status (Admin/Analyst)

Seeded Data

After running seeders, the database will contain:

Users

• Admin: admin@fhl.com / password: admin123
• Analyst: analyst@fhl.com / password: analyst123

Clients

• Multiple test clients with valid ID cards and delivery addresses

Warehouses

• Central Warehouse (Active)
• North Warehouse (Active)
• South Warehouse (Active)

Products

• Various products with stock distributed across warehouses

Validations

The system includes the following validations:

1. Stock Validation: Orders cannot be created if there's insufficient stock in the selected warehouse
2. Unique ID Card: Clients cannot be registered with duplicate ID cards
3. Valid Order Status: Only valid status transitions are allowed (pending → in_transit → delivered)
4. Role-based Access: Endpoints are protected based on user roles

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Project Structure

Order Management System/
├── backend/
│   └── src/
│       ├── config/          # Configuration files (Swagger)
│       ├── controllers/     # Request handlers
│       ├── database/        # Seeders
│       ├── interfaces/      # TypeScript interfaces
│       ├── jobs/            # Cron jobs
│       ├── middleware/      # Auth & validation middleware
│       ├── models/          # Sequelize models
│       ├── routes/          # API routes
│       ├── services/        # Business logic
│       ├── tests/           # Unit tests
│       ├── types/           # Type definitions
│       ├── utils/           # Helper functions
│       └── app.ts           # Application entry point
├── frontend/                # Frontend (reserved for future implementation)
├── postman/                 # Postman collection & environment
│   ├── FHL_Order_Management_System.postman_collection.json
│   ├── FHL_Environment.postman_environment.json
│   └── README.md
├── scripts/                 # Utility scripts
│   └── generate-dump.sh     # SQL dump generator
├── .env                     # Environment variables (not in repo)
├── .env.example             # Environment template
├── package.json             # Dependencies
├── tsconfig.json            # TypeScript configuration
├── QUICK_START.md           # Quick setup guide
├── IMPLEMENTATION_SUMMARY.md # Implementation checklist
└── README.md                # This file

Git Workflow

This project follows Git Flow with conventional commits:

Branches

• main - Production-ready code
• develop - Development branch
• feature/* - Feature branches

Commit Convention

feat: Add new feature
fix: Fix bug
docs: Update documentation
style: Code style changes
refactor: Code refactoring
test: Add tests
chore: Maintenance tasks

SQL Dump

Generating the SQL Dump

To generate a SQL dump with the current database structure and data:

# Using the provided script
./scripts/generate-dump.sh

# Or manually
npm run db:dump

This will create a file at database/dump.sql with:

• Complete database structure (tables, constraints, indexes)
• All seeded data
• Clean and recreate commands

Restoring from SQL Dump

To restore the database from the dump file:

psql -U postgres < database/dump.sql

Or if the database already exists:

psql -U postgres -d deliverydb < database/dump.sql

Support

For issues or questions, please contact the development team.

License

ISC