Supply Chain Management System

A comprehensive NestJS backend for managing supply chain operations including inventory, suppliers, warehouses, and purchase orders.

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• pnpm (v8 or higher)
• Docker and Docker Compose
• Git

📥 Installation

1. Clone the repository

   git clone <your-repo-url>
   cd supply-chain-management

2. Install dependencies using pnpm

   pnpm install

3. Setup Environment Variables

   cp .env.example .env

   Edit .env file with this configuration:

   # Global settings
   COMPOSE_PROJECT_NAME=inventory-management
   
   # Database
   DB_HOST=postgres
   DB_PORT=5432
   DB_NAME=inventory_management
   DB_USERNAME=postgres
   DB_PASSWORD=db@_123445
   
   # Redis
   REDIS_HOST=redis
   REDIS_PORT=6379
   REDIS_PASSWORD=redis@12345
   REDIS_USERNAME=default
   
   # Mail (SMTP)
   MAIL_PORT=465
   MAIL_HOST=smtp.gmail.com
   MAIL_USER=ukuanovweogheneovo@gmail.com
   MAIL_PASSWORD=mail_password@gmail.com
   MAIL_FROM=inventoryx@gmail.com
   
   # App
   NODE_ENV=production
   PORT=3000
   COMPOSE_PROJECT_NAME=souk-inventory
   CLIENT_URL=http://localhost:3000
   
   # JWT Secrets (different per environment)
   JWT_ACCESS_SECRET=althub_bazar_$$$Root
   JWT_REFRESH_SECRET=althub_bazar_@_43v3r!
   
   # Seeding Configs
   ADMIN_EMAIL=ukuanovweogheneovo@gmail.com
   ADMIN_PASSWORD=test@_1321!
   MANAGER_EMAIL=xorbious@gmail.com
   MANAGER_PASSWORD=test@_1321!

   Important: Update the MAIL_PASSWORD with your actual Gmail app password.

4. Start with Docker (Recommended)

    docker-compose --env-file .env up -d --build

   This starts:

   • PostgreSQL database on port 5432
   • Redis on port 6379
   • Your NestJS app on port 3000

🌱 Initial Setup & Seeding

After starting the application for the first time, run the seeder:

# Run the database seeder
pnpm run seed

This will create:

• ✅ Default roles and permissions (Admin, Manager, Supplier, Default)
• ✅ Admin user account with email: ukuanovweogheneovo@gmail.com
• ✅ Manager user account with email: xorbious@gmail.com
• ✅ Initial warehouse
• ✅ Warehouse manager account

Default Login Credentials:

• Admin: ukuanovweogheneovo@gmail.com / test@_1321!
• Manager: xorbious@gmail.com / test@_1321!

🛠️ Manual Setup (Without Docker)

1. Setup Database

   • Install PostgreSQL
   • Create database: inventory_management
   • Update .env with your DB credentials (set DB_HOST=localhost)

2. Setup Redis

   # On macOS
   brew install redis
   redis-server
   
   # On Ubuntu
   sudo apt install redis-server
   redis-server

3. Run Database Migrations

   pnpm run typeorm:run

4. Start the Application

   # Development
   pnpm run start:dev
   
   # Production
   pnpm run build
   pnpm run start:prod

5. Run Seeder (Important!)

   pnpm run seed

🧪 Testing the Setup

1. Check Services are Running

   # Check containers
   docker ps
   
   # Test API
   curl http://localhost:3000/health

2. Test Authentication

   # Login with admin account
   curl -X POST http://localhost:3000/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "email": "ukuanovweogheneovo@gmail.com",
       "password": "test@_1321!"
     }'

3. Verify Seeder Ran Successfully Check your terminal for seeder completion message and account details.

📚 API Documentation

Once running, access API docs at: http://localhost:3000/swagger-docs

🏗️ Project Structure

src/
├── auth/          # Authentication & authorization
├── users/         # User & Supplier Profile management
├── inventory/     # Products & Product Suppliers
├── warehouses/    # Warehouse management
├── orders/        # Purchase orders
├── rbac/          # Roles and Permission 
├── common/        # Shared utilities
├── errors/        # Error Service 
├── mail/          # Email services
└── seeds/         # Seed Factory

🔧 Development Commands

# Development mode with hot-reload
pnpm run start:dev

# Build project
pnpm run build

# Run tests
pnpm test

# Run linting
pnpm run lint

# Database migrations
pnpm run typeorm:generate    # Generate new migration
pnpm run typeorm:run         # Run migrations
pnpm run typeorm:revert      # Revert last migration

# Database seeding (CRITICAL for first setup)
pnpm run seed

🐛 Troubleshooting

Common Issues

1. Port already in use

   # Find and kill process
   lsof -ti:3000 | xargs kill -9

2. Database connection issues

   • Check PostgreSQL is running
   • Verify credentials in .env
   • Ensure database exists

3. Seeder fails to run

   • Make sure database is running and accessible
   • Check that migrations have run successfully
   • Verify environment variables are set correctly

4. Email configuration

   • Use Gmail App Password, not your regular Gmail password
   • Enable 2-factor authentication in Gmail
   • Generate app password from Google Account settings

5. pnpm not found

   # Install pnpm globally
   npm install -g pnpm

Logs & Debugging

# View container logs
docker-compose logs app
docker-compose logs postgres
docker-compose logs redis

# View specific service logs
docker-compose logs -f app

📦 Default Ports

• API Server: 3000
• PostgreSQL: 5432
• Redis: 6379

🔐 Default Accounts

After running the seeder, you'll have these accounts:

Role	Email	Password	Purpose
Admin	ukuanovweogheneovo@gmail.com	test@_1321!	Full system access
Manager	xorbious@gmail.com	test@_1321!	Warehouse management

⚠️ Production Considerations & Unimplemented Features

While this project is designed to be production-ready with proper authentication, RBAC, and database architecture, there are several important features that were not implemented:

🔴 Not Yet Implemented

1. Automatic Product SKU Generation

• Currently, SKUs must be manually provided when creating products
• Suggested Implementation: Auto-generate SKUs using patterns like:

  // Example: CAT-001-2024, ELEC-002-2024
  generateSKU(category: string, sequence: number): string {
    return `${category.toUpperCase().substring(0,4)}-${sequence.toString().padStart(3,'0')}-${new Date().getFullYear()}`;
  }

2. Role-Based Data Filtering & Access Restrictions

• Basic RBAC is implemented but lacks data-level filtering
• Missing: Suppliers can only see their assigned products
• Missing: Managers can only access warehouses they manage
• Suggested Solution: Use NestJS RBAC filter API with query interceptors:

  @RBAcAsyncPermissions(`permission5@${ASYNC_RBAC_REQUEST_FILTER}`)
  async getProducts() {
    // Automatically filters based on user role and assignments
  }

3. Advanced Features Not Covered

• Data Export: CSV/Excel export functionality for reports
• WebSocket Integration: Real-time inventory updates
• API Rate Limiting Per Endpoint: More granular rate limiting
• Data Backup & Recovery: Automated backup strategies

🟡 Partially Implemented

1. Email System

• Basic template system exists but limited template variety 2. Advanced Reporting
• Analytics dashboards, trend analysis

🟢 Fully Implemented

• ✅ Complete Authentication & Authorization
• ✅ RBAC with configurable permissions
• ✅ Database migrations and seeding
• ✅ Docker containerization
• ✅ Redis caching and queue management
• ✅ Email service integration (Delivery,Tracking and Retry Strategy Via Redis and Bull Queues)
• ✅ Comprehensive entity relationships
• ✅ API documentation via swagger docs
• ✅ Rate limiting and security measures
• ✅ Basic reorder threshold checking
• ✅ Email Notification for (low stock alerts, automatic Purchase Order Request, Stock Level Adjustment)
• ✅ Bulk Operations**: Mass product imports, inventory updates
• ✅ Responsive design for mobile devices

🚀 Deployment

For production deployment:

1. Set NODE_ENV=production in .env
2. Update CORS origins and client URLs
3. Use proper SSL certificates
4. Set up reverse proxy (nginx)
5. Configure production database
6. Run seeder in production environment
7. Change default passwords for security

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request

📄 License

This project is licensed under the MIT License.

---

Need Help? Check the issues section or create a new issue with your problem details.

Remember:

1. Run pnpm run seed after first startup to create admin account and essential data!
2. Update MAIL_PASSWORD with your actual Gmail app password to enable email features!