📦 Inventory Management System

A full-stack Inventory Management System built with FastAPI, PostgreSQL, and React. This project is designed to help businesses manage products, categories, suppliers, inventory, purchases, and sales efficiently through a secure REST API and modern web interface.

This project is being developed following real-world software engineering practices, including modular architecture, version control, clean code principles, and RESTful API design.

---

🚀 Features

Authentication & Authorization

• JWT Authentication
• Secure Password Hashing (bcrypt)
• Role-Based Access Control (Admin, Manager, Staff)
• Protected API Routes

User Management

• User Registration
• User Login
• View User Profile
• Update User Profile
• Manage User Roles

Category Management

• Create Categories
• View Categories (with search & pagination)
• Update Categories
• Delete Categories

Product Management

• Add Products
• View Products (search, filter by category/price/stock, pagination)
• Update Product Information
• Delete Products
• Unique SKU Enforcement
• Category Reference Validation

Supplier Management

• Add Suppliers
• View Suppliers (with search & pagination)
• Update Supplier Information
• Delete Suppliers

Purchase Management

• Record Purchases (with one or more line items)
• Purchase Items
• Automatic Stock Increment (atomic transaction per request)
• Supplier & Product Reference Validation

Sales Management

• Record Sales (with one or more line items)
• Sale Items
• Automatic Stock Deduction (atomic transaction per request)
• Insufficient-Stock Rejection (whole sale rejected, no partial writes)

Inventory (planned)

• Current Stock Levels
• Low Stock Alerts
• Inventory Reports

Dashboard & Reports

• Store-Wide Summary (products, categories, suppliers, stock units, stock value, purchases, sales, revenue)
• Low-Stock Alerts (configurable threshold, sorted lowest first)
• Top-Selling Products (ranked by quantity sold, with revenue)

---

🛠 Tech Stack

Backend

• FastAPI
• SQLAlchemy ORM
• PostgreSQL
• Alembic
• Pydantic
• JWT Authentication
• Passlib (bcrypt)

Frontend

• React
• Vite
• React Router
• Native Fetch API (thin wrapper in api/client.js)
• Hand-written CSS (design tokens in index.css)

Database

• PostgreSQL

Development Tools

• Git
• GitHub
• VS Code
• Postman

---

📁 Project Structure

inventory-management-system/
├── backend/
│   ├── app/
│   │   ├── core/
│   │   ├── dependencies/
│   │   ├── middleware/
│   │   ├── models/
│   │   ├── routers/
│   │   ├── schemas/
│   │   ├── services/
│   │   ├── utils/
│   │   ├── config.py
│   │   ├── database.py
│   │   └── main.py
│   ├── .env
│   └── requirements.txt
├── frontend/
├── docs/
├── .gitignore
└── README.md

---

🗄 Database Entities

• Users
• Categories
• Products
• Suppliers
• Purchases
• Purchase Items
• Sales
• Sale Items

🔗 Entity Relationships

• One Category → Many Products
• One Supplier → Many Purchases
• One Purchase → Many Purchase Items
• One Product → Many Purchase Items
• One Sale → Many Sale Items
• One Product → Many Sale Items

🔐 User Roles

Role	Permissions
Admin	Full system access
Manager	Manage inventory, purchases, and sales
Staff	Limited inventory operations

---

⚙️ Installation

Clone Repository

git clone https://github.com/studyhaxer/inventory-management-system.git
cd inventory-management-system

Backend Setup

Create virtual environment

python -m venv venv

Activate virtual environment

Windows

venv\Scripts\activate

Linux / macOS

source venv/bin/activate

Install dependencies

pip install -r requirements.txt

Configure Environment Variables

Create a .env file inside backend/app/ (this is the path used by docker-compose.yml and .gitignore).

DATABASE_URL=postgresql://username:password@localhost/inventory_db
SECRET_KEY=your_secret_key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

Run the Backend

Locally, from backend/:

uvicorn main:app --app-dir app --reload

With Docker (also starts PostgreSQL and the frontend), from the project root:

docker-compose up --build

• Server: http://127.0.0.1:8000
• Swagger Documentation: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

---

🗺 Development Roadmap

Phase 1

• Project Setup
• Database Design
• PostgreSQL Configuration
• SQLAlchemy Setup

Phase 2

• User Authentication
• JWT Login
• Role-Based Authorization

Phase 3

• ERD-based SQLAlchemy models (Category, Product, Supplier, Purchase, PurchaseItem, Sale, SaleItem)
• Alembic initialized and wired to Base.metadata
• Initial migrations generated, reviewed, and applied to Supabase Postgres (core inventory tables + users table)
• Category & Supplier CRUD endpoints
• Request validation & search filtering

Phase 4

• Product CRUD endpoints (create, list, get, update, delete)
• Filtering (category, price range, stock status) and search (name/SKU)
• Pagination (skip/limit) matching Category/Supplier pattern
• Unique SKU and category_id reference validation

Phase 5

• Supplier Module (completed under Phase 3 alongside Category Module)

Phase 6

• Purchase Module (schemas, CRUD endpoints, atomic stock increment, supplier/product validation)

Phase 7

• Sales Module (schemas, CRUD endpoints, atomic stock decrement, insufficient-stock rejection)

Phase 8

• Inventory Reports

Phase 9

• Dashboard APIs (summary, low-stock, top-products endpoints with SQL aggregates)

Phase 10

• React Frontend — Auth UI (login, register, JWT session handling, protected routes)
• React Frontend — Dashboard summary UI (store-wide summary cards)
• React Frontend — CRUD UI (categories, suppliers, products)
• React Frontend — Purchases & Sales CRUD UI (append-only ledger views, dynamic line-item forms)
• React Frontend — Low-stock alerts & top-selling products views (CSS bar chart, low-stock panel, responsive layout across nav/cards/tables)

---

📖 API Documentation

Interactive API documentation is available after running the server.

Swagger UI

/docs

ReDoc

/redoc

---

🧪 Testing

API and UI testing has been performed manually using:

• Swagger UI
• Postman
• Manual browser verification (including responsive/mobile-width checks)

Automated testing (pytest suite) was scoped for this project but not implemented before closing out — see Future Improvements below.

---

📈 Future Improvements

• Automated Testing (pytest suite: auth, RBAC, CRUD, purchase/sale stock side-effects, dashboard aggregates)
• Docker Compose Polish (service healthchecks, dependency ordering)
• Inventory Reports (Phase 8)
• Barcode Scanner Support
• Image Upload for Products
• Export Reports (PDF/Excel)
• Email Notifications
• Audit Logs
• CI/CD Pipeline

---

🤝 Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch

git checkout -b feature/your-feature

3. Commit your changes

git commit -m "Add new feature"

4. Push to GitHub

git push origin feature/your-feature

5. Create a Pull Request

---

👤 Author

Hafiz Atta Ur Rahman Backend Developer | Python | FastAPI | React

• GitHub: https://github.com/studyhaxer
• LinkedIn: https://linkedin.com/in/studyhaxer

---

📄 License

This project is licensed under the MIT License.

---

⭐ Project Status

✅ Core Feature-Complete — Closed for Active Development

This project was built incrementally as a structured, internship-style learning exercise covering full-stack development with FastAPI, PostgreSQL, and React: authentication and RBAC, full CRUD across all core resources, atomic purchase/sale stock transactions, dashboard aggregates with a live UI (summary, top-selling products, low-stock alerts), and a responsive frontend.

It is being closed out at this stage as a complete, working reference project. Automated testing, Docker Compose polish, and the items above under Future Improvements were scoped during development but intentionally left for a future pass rather than blocking closure of this iteration.