Supplier Management System with Node.js and MongoDB

A comprehensive supplier management REST API built with Node.js, Express, and MongoDB. This system provides complete CRUD operations for managing suppliers, purchase orders, and invoices, along with advanced business analytics.

Features

Core Modules

Items Management - Basic CRUD operations for items/products
Supplier Management - Register and manage suppliers with contact and address details
Purchase Order Management - Track purchase orders from creation to completion
Invoice Management - Manage invoices and payment tracking
Advanced Analytics - Business intelligence APIs for reporting and insights

Advanced Business Logic APIs (APIs Métier)

Supplier Statistics Dashboard - Comprehensive supplier performance metrics
Overdue Invoices Report - Track and manage overdue payments by supplier
Purchase Order Summary - Aggregated purchase data with filtering and trends

Prerequisites

Before running this application, make sure you have the following installed:

Node.js (v14 or higher)
MongoDB (local installation or MongoDB Atlas account)

Installation

Install dependencies:

npm install

Configure environment variables:
- Edit the .env file and update the MongoDB URI if needed
- Default connection: mongodb://localhost:27017/crud_db
Make sure MongoDB is running:
- For local MongoDB: Start the MongoDB service
- For MongoDB Atlas: Use your connection string in .env

Running the Application

Development mode (with auto-restart):

npm run dev

Production mode:

npm start

The server will start on http://localhost:3000

API Documentation

Items API

Get all items

GET /api/items

Get a single item

GET /api/items/:id

Create a new item

POST /api/items
Content-Type: application/json

{
  "name": "Product Name",
  "description": "Product Description",
  "price": 29.99,
  "quantity": 10,
  "category": "Electronics"
}

Update an item

PUT /api/items/:id

Delete an item

DELETE /api/items/:id

Suppliers API

Get all suppliers

GET /api/suppliers
Query Parameters:
  - status: Filter by status (active/inactive)
  - productType: Filter by product type
  - search: Search by supplier name

Get a single supplier

GET /api/suppliers/:id

Create a new supplier

POST /api/suppliers
Content-Type: application/json

{
  "name": "AgriSupply Inc.",
  "contact": {
    "phone": "+33123456789",
    "email": "contact@agrisupply.com"
  },
  "address": {
    "street": "123 Rue de Agriculture",
    "city": "Paris",
    "postalCode": "75001",
    "country": "France"
  },
  "productType": "Semences",
  "status": "active"
}

Product Types: Semences, Engrais, Matériel, Produits Agricoles, Autres

Update a supplier

PUT /api/suppliers/:id
Content-Type: application/json

{
  "status": "inactive"
}

Delete a supplier

DELETE /api/suppliers/:id
Note: Cannot delete if supplier has associated purchase orders

Purchase Orders API

Get all purchase orders

GET /api/purchase-orders
Query Parameters:
  - supplier: Filter by supplier ID
  - status: Filter by status (Pending/Completed/Cancelled)
  - startDate: Filter by order date (start)
  - endDate: Filter by order date (end)

Get a single purchase order

GET /api/purchase-orders/:id

Create a new purchase order

POST /api/purchase-orders
Content-Type: application/json

{
  "supplier": "SUPPLIER_ID",
  "items": [
    {
      "productName": "Wheat Seeds",
      "quantity": 100,
      "unitPrice": 15.50
    },
    {
      "productName": "Fertilizer",
      "quantity": 50,
      "unitPrice": 25.00
    }
  ],
  "expectedDeliveryDate": "2024-12-31",
  "notes": "Urgent order for winter season"
}

Note: Order number and total amount are auto-generated

Update a purchase order

PUT /api/purchase-orders/:id
Content-Type: application/json

{
  "status": "Completed"
}

Update purchase order status

PATCH /api/purchase-orders/:id/status
Content-Type: application/json

{
  "status": "Completed"
}

Delete a purchase order

DELETE /api/purchase-orders/:id

Invoices API

Get all invoices

GET /api/invoices
Query Parameters:
  - supplier: Filter by supplier ID
  - paymentStatus: Filter by payment status (Unpaid/Partial/Paid)
  - startDate: Filter by issue date (start)
  - endDate: Filter by issue date (end)

Get a single invoice

GET /api/invoices/:id

Create a new invoice

POST /api/invoices
Content-Type: application/json

{
  "purchaseOrder": "PURCHASE_ORDER_ID",
  "supplier": "SUPPLIER_ID",
  "amount": 2800.00,
  "dueDate": "2024-01-31",
  "notes": "Payment due within 30 days"
}

Note: Invoice number is auto-generated

Update an invoice

PUT /api/invoices/:id
Content-Type: application/json

{
  "dueDate": "2024-02-15"
}

Record payment for an invoice

PATCH /api/invoices/:id/payment
Content-Type: application/json

{
  "paymentAmount": 1000.00,
  "paymentMethod": "Bank Transfer",
  "paymentDate": "2024-01-15"
}

Payment Methods: Cash, Bank Transfer, Check, Credit Card, Other

Note: Payment status is automatically updated based on amount paid

Delete an invoice

DELETE /api/invoices/:id

Analytics API (Advanced Business Logic)

1. Supplier Statistics Dashboard

Get comprehensive statistics for a specific supplier

GET /api/analytics/supplier-stats/:supplierId

Response includes:
- Total orders count
- Pending/Completed/Cancelled orders
- Total amount spent
- Average order value
- Total invoices
- Unpaid invoices count
- Total unpaid amount
- Last order date and number

2. Overdue Invoices Report

Get all overdue invoices grouped by supplier

GET /api/analytics/overdue-invoices

Response includes:
- Summary (total overdue invoices, total amount, suppliers affected)
- Detailed breakdown by supplier
- Days overdue calculation
- Remaining amounts to be paid

3. Purchase Order Summary Report

Get aggregated purchase order data with advanced filtering

GET /api/analytics/purchase-summary
Query Parameters:
  - startDate: Start date for filtering
  - endDate: End date for filtering
  - supplierId: Filter by specific supplier
  - status: Filter by order status

Response includes:
- Overall summary (total orders, total amount, average order value)
- Status breakdown
- Spending by supplier
- Monthly trends
- Top 10 products ordered

Example Usage with cURL

Create a supplier

curl -X POST http://localhost:3000/api/suppliers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FarmSupplies Pro",
    "contact": {
      "phone": "+33987654321",
      "email": "info@farmsupplies.fr"
    },
    "address": {
      "street": "45 Avenue des Champs",
      "city": "Lyon",
      "postalCode": "69001",
      "country": "France"
    },
    "productType": "Engrais",
    "status": "active"
  }'

Create a purchase order

curl -X POST http://localhost:3000/api/purchase-orders \
  -H "Content-Type: application/json" \
  -d '{
    "supplier": "YOUR_SUPPLIER_ID",
    "items": [
      {
        "productName": "Organic Fertilizer",
        "quantity": 200,
        "unitPrice": 12.50
      }
    ],
    "expectedDeliveryDate": "2024-12-25"
  }'

Get overdue invoices report

curl http://localhost:3000/api/analytics/overdue-invoices

Get purchase summary for date range

curl "http://localhost:3000/api/analytics/purchase-summary?startDate=2024-01-01&endDate=2024-12-31"

Project Structure

├── config/
│   └── database.js              # MongoDB connection configuration
├── controllers/
│   ├── itemController.js        # Items CRUD logic
│   ├── supplierController.js    # Supplier CRUD logic
│   ├── purchaseOrderController.js # Purchase orders CRUD logic
│   ├── invoiceController.js     # Invoice CRUD logic
│   └── analyticsController.js   # Advanced business analytics
├── models/
│   ├── Item.js                  # Item schema
│   ├── Supplier.js              # Supplier schema
│   ├── PurchaseOrder.js         # Purchase order schema
│   └── Invoice.js               # Invoice schema
├── routes/
│   ├── itemRoutes.js            # Item API routes
│   ├── supplierRoutes.js        # Supplier API routes
│   ├── purchaseOrderRoutes.js   # Purchase order API routes
│   ├── invoiceRoutes.js         # Invoice API routes
│   └── analyticsRoutes.js       # Analytics API routes
├── .env                         # Environment variables
├── .gitignore                   # Git ignore file
├── package.json                 # Project dependencies
├── server.js                    # Main application entry point
├── README.md                    # Project documentation
├── TESTING.md                   # Testing documentation
└── BUSINESS_TESTING.md          # Business features testing guide

Technologies Used

Node.js - JavaScript runtime
Express.js - Web framework
MongoDB - NoSQL database
Mongoose - MongoDB ODM with schema validation
dotenv - Environment variable management
body-parser - Request body parsing middleware

Key Features

Auto-Generation

Purchase order numbers (format: PO-YYYYMM-00001)
Invoice numbers (format: INV-YYYYMM-00001)

Data Validation

Email format validation
Required fields enforcement
Referential integrity checks
Payment amount validation

Business Logic

Automatic calculation of order totals
Payment status updates (Unpaid → Partial → Paid)
Overdue invoice detection
Supplier deletion protection

Performance Optimization

Indexed fields for faster queries
Population of related documents
Efficient aggregation queries

Testing

For detailed testing instructions using Postman, see BUSINESS_TESTING.md

License

ISC

Name		Name	Last commit message	Last commit date
config		config
controllers		controllers
models		models
routes		routes
.gitignore		.gitignore
BUSINESS_TESTING.md		BUSINESS_TESTING.md
README.md		README.md
TESTING.md		TESTING.md
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

Latest commit

History

Folders and files

Repository files navigation