Procurement System

A modern, full-featured procurement management system built with FastAPI (Python backend) and React (TypeScript frontend). This system provides comprehensive tools for managing suppliers, products, purchase orders, inventory, shipments, and procurement workflows.

Features

• User Management: Role-based access control with admin, procurement manager, inventory manager, finance approver, and viewer roles
• Supplier Management: Complete supplier lifecycle management with status tracking and categorization (manufacturer, distributor, wholesaler, service provider)
• Product Catalog: Hierarchical product categories with active/discontinued status management
• Purchase Orders: Full PO workflow including draft, approval, ordering, receiving, and cancellation states
• Inventory Management: Real-time inventory tracking with adjustment types (receipt, issue, adjustment, return, damage)
• Shipment Tracking: Multi-modal shipment support (air, sea, land, rail, multimodal) with status monitoring
• Audit Logging: Comprehensive logging of all operations with request tracking and performance metrics
• API Documentation: Auto-generated OpenAPI/Swagger documentation
• Authentication: JWT-based authentication with access and refresh tokens
• File Storage: MinIO object storage integration for document management
• Email Notifications: Configurable email integration for alerts and notifications
• Caching: Redis integration for performance optimization
• Rate Limiting: Built-in request rate limiting and burst protection

Tech Stack

Backend:

• FastAPI (Python web framework)
• PostgreSQL (relational database)
• Redis (caching and task queue)
• Alembic (database migrations)
• Celery (async task processing)
• MinIO (object storage)
• SQLAlchemy (ORM)

Frontend:

• React 18+ (UI library)
• TypeScript (type-safe JavaScript)
• Tailwind CSS (utility-first CSS)
• Vite (build tool)

DevOps:

• Docker & Docker Compose
• PostgreSQL container
• Redis container
• MinIO container

Setup Instructions

Prerequisites

• Docker and Docker Compose installed
• Python 3.9+ (for local development without Docker)
• Node.js 16+ (for frontend development)

Quick Start with Docker

1. Clone the repository:

   git clone <repository-url>
   cd procurement-system

2. Copy environment file:

   cp .env.example .env

3. Review and update the .env file with your configuration:

   • Change SECRET_KEY to a secure random string in production
   • Update FIRST_SUPERUSER_PASSWORD
   • Configure email settings (SMTP_HOST, SMTP_USERNAME, SMTP_PASSWORD)
   • Set external API keys (SHIPPING_API_KEY, PAYMENT_GATEWAY_API_KEY)
   • Update MinIO credentials if using a non-local setup

4. Start all services:

   docker-compose up -d

5. Access the services:

   • Frontend: http://localhost:3000 (or configured port)
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/api/v1/docs
   • Health Check: http://localhost:8000/health

Local Development Setup

Backend:

cd procurement-system/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run.py

Frontend:

cd procurement-system/frontend
npm install
npm run dev

Configuration

All configuration is managed through environment variables in the .env file:

• APPLICATION: PROJECT_NAME, VERSION, ENVIRONMENT, DEBUG
• SECURITY: SECRET_KEY, ALGORITHM, token expiration times
• DATABASE: DATABASE_URL, PostgreSQL credentials
• CACHE: REDIS_URL
• CORS: BACKEND_CORS_ORIGINS, ALLOWED_HOSTS
• STORAGE: MinIO endpoint and credentials
• EMAIL: SMTP configuration for notifications
• MONITORING: Sentry DSN, New Relic key (optional)
• RATE LIMITING: Requests per minute and burst limits
• LOGGING: Log level configuration

For a complete reference, see .env.example.

API Usage Example

Authentication

# Login to get access token
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@procurement-system.com","password":"changethis123"}'

# Response includes: access_token, token_type, expires_in

Creating a Supplier

curl -X POST http://localhost:8000/api/v1/suppliers \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supplier Inc",
    "email": "contact@supplier.com",
    "status": "active",
    "category": "manufacturer"
  }'

Listing Products

curl -X GET "http://localhost:8000/api/v1/products?skip=0&limit=10" \
  -H "Authorization: Bearer {access_token}"

Full API documentation is available at http://localhost:8000/api/v1/docs once the backend is running.

Database Migrations

Migrations are managed with Alembic:

# Apply pending migrations
alembic upgrade head

# Create a new migration
alembic revision --autogenerate -m "description"

# Downgrade to previous version
alembic downgrade -1

Documentation

See the docs/ directory for additional documentation:

• Docker Compose guide
• Contributing guidelines
• Bug fixes summary
• License information

Development

Running Tests

cd backend
pytest

Code Style

• Backend: Follow PEP 8 (enforced with tools like black, flake8)
• Frontend: ESLint and Prettier configurations included

Contributing

See CONTRIBUTING.md for guidelines on submitting issues and pull requests.

Troubleshooting

Common Issues

Database connection error:

• Ensure PostgreSQL container is running: docker-compose ps
• Check DATABASE_URL in .env matches your setup

API not responding:

• Check backend health: curl http://localhost:8000/health
• Review backend logs: docker-compose logs backend

Frontend can't reach API:

• Verify VITE_API_URL in .env points to correct backend address
• Check CORS settings in BACKEND_CORS_ORIGINS

License

See LICENSE file for details.

Support

For issues, feature requests, or questions, please open an issue on the repository or refer to the documentation.