smallbusinessinventorymanagementsystem-r5ffzu/README.md

Small Business Inventory Management System

A FastAPI-based REST API for managing inventory in small businesses. This system helps small businesses track inventory, manage stock levels, categorize products, and generate reports.

Features

• User Authentication and Authorization

  • JWT-based authentication
  • Role-based permissions (admin/regular users)
  • Secure password hashing

• Inventory Management

  • Add, update, and delete inventory items
  • Track stock levels and set reorder points
  • Assign items to categories
  • Track item history with SKU

• Category Management

  • Organize items into categories
  • Nested categorization support
  • Category-based reporting

• Transaction Tracking

  • Record purchases, sales, returns, and adjustments
  • Automatic stock level updates
  • Transaction history for audit purposes

• Reporting

  • Inventory value reports
  • Category summary reports
  • Low stock alerts
  • Transaction summary reports

• API Features

  • RESTful endpoints following best practices
  • Comprehensive documentation with Swagger UI
  • Health check endpoint for monitoring

Tech Stack

• FastAPI: Modern, fast web framework for building APIs
• SQLAlchemy: SQL toolkit and ORM
• Alembic: Database migration tool
• SQLite: Simple, file-based database
• Pydantic: Data validation and settings management
• Uvicorn: ASGI server for FastAPI
• Python-Jose: JWT token handling
• Passlib: Password hashing
• Ruff: Python linter for code quality

Project Structure

.
├── app/
│   ├── api/
│   │   ├── deps.py                   # Dependency injection
│   │   └── v1/
│   │       ├── api.py                # API router
│   │       └── endpoints/
│   │           ├── auth.py           # Authentication endpoints
│   │           ├── categories.py     # Category endpoints
│   │           ├── health.py         # Health check endpoint
│   │           ├── items.py          # Inventory item endpoints
│   │           ├── reports.py        # Reporting endpoints
│   │           ├── transactions.py   # Transaction endpoints
│   │           └── users.py          # User endpoints
│   ├── core/
│   │   ├── config.py                 # Application configuration
│   │   └── security.py               # Security utilities
│   ├── crud/
│   │   ├── base.py                   # Base CRUD operations
│   │   ├── category.py               # Category CRUD
│   │   ├── item.py                   # Item CRUD
│   │   ├── transaction.py            # Transaction CRUD
│   │   └── user.py                   # User CRUD
│   ├── db/
│   │   ├── init_db.py                # Database initialization
│   │   ├── session.py                # Database session
│   │   └── utils.py                  # Database utilities
│   ├── models/                       # SQLAlchemy models
│   │   ├── base.py                   # Base model
│   │   ├── category.py               # Category model
│   │   ├── item.py                   # Item model
│   │   ├── transaction.py            # Transaction model
│   │   └── user.py                   # User model
│   ├── schemas/                      # Pydantic schemas
│   │   ├── category.py               # Category schemas
│   │   ├── item.py                   # Item schemas
│   │   ├── report.py                 # Report schemas
│   │   ├── token.py                  # Token schemas
│   │   ├── transaction.py            # Transaction schemas
│   │   └── user.py                   # User schemas
│   └── storage/                      # Storage directory
│       └── db/                       # Database storage
├── migrations/                       # Alembic migrations
│   ├── env.py                        # Alembic environment
│   ├── script.py.mako               # Migration script template
│   └── versions/                     # Migration versions
│       └── initial_migration.py     # Initial database schema
├── alembic.ini                       # Alembic configuration
├── main.py                           # Application entry point
├── pyproject.toml                    # Project configuration
└── requirements.txt                  # Dependencies

Authentication Flow

The system implements a complete authentication flow with the following features:

User Registration and Email Verification

1. Users register via POST /api/v1/auth/register with their email, password, and optional details
2. The system creates a new user account with a verification token
3. If email sending is enabled, a verification email is sent to the user's email address
4. Users verify their email by clicking the link in the email, which calls POST /api/v1/auth/verify-email
5. Email verification is optional by default but can be enforced by uncommenting the verification check in the login endpoint

Login and Authentication

1. Users login via POST /api/v1/auth/login with their email (as username) and password
2. Upon successful authentication, the system returns a JWT access token
3. This token must be included in the Authorization header as Bearer {token} for protected endpoints
4. Tokens expire after the time specified in ACCESS_TOKEN_EXPIRE_MINUTES (default: 8 days)

Password Reset Flow

1. Users request a password reset via POST /api/v1/auth/password-reset-request with their email
2. If the email exists, a reset token is generated and a reset link is sent to the user's email
3. Users reset their password via POST /api/v1/auth/reset-password with the token and new password
4. Reset tokens expire after the time specified in PASSWORD_RESET_TOKEN_EXPIRE_HOURS (default: 24 hours)

Environment Variables for Authentication

The following environment variables can be configured:

# Security
SECRET_KEY="your-secret-key-here"
ACCESS_TOKEN_EXPIRE_MINUTES=11520  # 8 days

# Email verification
EMAILS_ENABLED=True
VERIFICATION_TOKEN_EXPIRE_HOURS=48
PASSWORD_RESET_TOKEN_EXPIRE_HOURS=24

# SMTP settings for email
SMTP_TLS=True
SMTP_PORT=587
SMTP_HOST=smtp.example.com
SMTP_USER=user@example.com
SMTP_PASSWORD=your-smtp-password
EMAILS_FROM_EMAIL=noreply@example.com
EMAILS_FROM_NAME=YourAppName

# First Superuser
FIRST_SUPERUSER_EMAIL=admin@example.com
FIRST_SUPERUSER_PASSWORD=adminpassword

Getting Started

Prerequisites

• Python 3.8 or higher

Installation

1. Clone the repository
2. Install dependencies:

pip install -r requirements.txt

3. Initialize the database:

alembic upgrade head

4. (Optional) Create a .env file in the root directory to customize environment variables:

PROJECT_NAME="My Inventory System"
SECRET_KEY="your-secret-key-here"
ACCESS_TOKEN_EXPIRE_MINUTES=1440  # 24 hours

5. Run the application:

uvicorn main:app --reload

6. Open http://localhost:8000/docs to access the Swagger UI documentation

API Documentation

• OpenAPI Documentation: /docs

  • Interactive API documentation with Swagger UI
  • Test endpoints directly from the browser

• Alternative Documentation: /redoc

  • Alternative documentation interface

• OpenAPI JSON: /openapi.json

  • Raw OpenAPI specification

API Endpoints

Authentication

• POST /api/v1/auth/register - Register a new user
• POST /api/v1/auth/login - Obtain JWT token
• POST /api/v1/auth/verify-email - Verify user's email address
• POST /api/v1/auth/password-reset-request - Request password reset
• POST /api/v1/auth/reset-password - Reset password with token
• POST /api/v1/auth/test-token - Test token validity

Users

• GET /api/v1/users/ - List users (admin only)
• POST /api/v1/users/ - Create user (admin only)
• GET /api/v1/users/me - Get current user
• PUT /api/v1/users/me - Update current user
• GET /api/v1/users/{user_id} - Get user by ID
• PUT /api/v1/users/{user_id} - Update user (admin only)

Categories

• GET /api/v1/categories/ - List categories
• POST /api/v1/categories/ - Create category (admin only)
• GET /api/v1/categories/{id} - Get category by ID
• PUT /api/v1/categories/{id} - Update category (admin only)
• DELETE /api/v1/categories/{id} - Delete category (admin only)

Inventory Items

• GET /api/v1/items/ - List items (with filtering options)
• POST /api/v1/items/ - Create item
• GET /api/v1/items/{id} - Get item by ID
• PUT /api/v1/items/{id} - Update item
• DELETE /api/v1/items/{id} - Delete item
• GET /api/v1/items/by-sku/{sku} - Get item by SKU
• GET /api/v1/items/low-stock/ - Get low stock items

Transactions

• GET /api/v1/transactions/ - List transactions (with filtering options)
• POST /api/v1/transactions/ - Create transaction
• GET /api/v1/transactions/{id} - Get transaction by ID

Reports

• GET /api/v1/reports/inventory-value - Inventory value report
• GET /api/v1/reports/category-summary - Category summary report
• GET /api/v1/reports/low-stock - Low stock report
• GET /api/v1/reports/transaction-summary - Transaction summary report

Health Check

• GET /health - System health check
• GET /api/v1/health - Detailed health check with DB status

Development

Linting

The project uses Ruff for linting:

ruff check .

Running Tests

pytest

License

This project is licensed under the MIT License.