smallbusinessinventorymanagementsystem-peyeuy/README.md

# Small Business Inventory Management System

A comprehensive FastAPI-based inventory management system designed for small businesses to track products, manage suppliers, monitor stock levels, and handle inventory transactions.

## Features

- **Product Management**: Add, update, and track inventory items with detailed information
- **Category Management**: Organize products into categories for better organization
- **Supplier Management**: Maintain supplier information and relationships
- **Stock Tracking**: Real-time stock level monitoring with low stock alerts
- **Transaction History**: Complete audit trail of all stock movements
- **Authentication**: Secure JWT-based authentication system
- **Search & Filtering**: Powerful search capabilities across inventory items
- **RESTful API**: Clean, well-documented API endpoints

## Technology Stack

- **Framework**: FastAPI
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT tokens with PassLib for password hashing
- **Migration**: Alembic for database migrations
- **Validation**: Pydantic for data validation
- **Documentation**: Auto-generated OpenAPI/Swagger documentation

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Run database migrations:
```bash
alembic upgrade head
```

3. Start the application:
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

## Environment Variables

The following environment variables can be set to configure the application:

- `SECRET_KEY`: JWT secret key (default: "your-secret-key-change-this-in-production")
- `FIRST_SUPERUSER_EMAIL`: Admin user email (default: "admin@inventory.com")
- `FIRST_SUPERUSER_PASSWORD`: Admin user password (default: "admin123")

**Important**: Change the default SECRET_KEY and admin credentials in production!

## API Documentation

Once the application is running, you can access:

- **Interactive API Documentation**: http://localhost:8000/docs
- **Alternative Documentation**: http://localhost:8000/redoc
- **OpenAPI Schema**: http://localhost:8000/openapi.json

## API Endpoints

### Authentication
- `POST /auth/login` - User login

### Categories
- `GET /categories/` - List all categories
- `POST /categories/` - Create new category
- `GET /categories/{id}` - Get category by ID
- `PUT /categories/{id}` - Update category
- `DELETE /categories/{id}` - Delete category

### Suppliers
- `GET /suppliers/` - List all suppliers
- `POST /suppliers/` - Create new supplier
- `GET /suppliers/{id}` - Get supplier by ID
- `PUT /suppliers/{id}` - Update supplier
- `DELETE /suppliers/{id}` - Delete supplier

### Items
- `GET /items/` - List all items
- `POST /items/` - Create new item
- `GET /items/{id}` - Get item by ID
- `PUT /items/{id}` - Update item
- `DELETE /items/{id}` - Delete item
- `GET /items/search?query={query}` - Search items
- `GET /items/low-stock` - Get items with low stock
- `GET /items/active` - Get active items only

### Stock Transactions
- `GET /stock-transactions/` - List all transactions
- `POST /stock-transactions/` - Create new transaction (updates stock automatically)
- `GET /stock-transactions/{id}` - Get transaction by ID
- `GET /stock-transactions/item/{item_id}` - Get transactions for specific item
- `GET /stock-transactions/type/{type}` - Get transactions by type (in/out/adjustment)

### System
- `GET /` - API information and links
- `GET /health` - Health check endpoint

## Database Schema

The system uses the following main entities:

- **Users**: System users with authentication
- **Categories**: Product categories for organization
- **Suppliers**: Supplier information and contacts
- **Items**: Inventory items with pricing and stock information
- **StockTransactions**: Record of all stock movements

## Usage Examples

### 1. Login
```bash
curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@inventory.com", "password": "admin123"}'
```

### 2. Create a Category
```bash
curl -X POST "http://localhost:8000/categories/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Electronics", "description": "Electronic devices and components"}'
```

### 3. Add an Item
```bash
curl -X POST "http://localhost:8000/items/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Laptop Computer",
    "description": "High-performance laptop",
    "sku": "LAP001",
    "unit_price": 999.99,
    "cost_price": 750.00,
    "quantity_in_stock": 10,
    "minimum_stock_level": 2,
    "reorder_point": 5,
    "category_id": 1
  }'
```

### 4. Record Stock Transaction
```bash
curl -X POST "http://localhost:8000/stock-transactions/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": 1,
    "transaction_type": "out",
    "quantity": 2,
    "reference_number": "SALE001",
    "notes": "Sale to customer"
  }'
```

## Development

### Running with Auto-reload
```bash
uvicorn main:app --reload
```

### Code Formatting
The project uses Ruff for linting and formatting:
```bash
ruff check .
ruff format .
```

### Database Migrations
Create a new migration:
```bash
alembic revision --autogenerate -m "Description of changes"
```

Apply migrations:
```bash
alembic upgrade head
```

## Production Deployment

1. Set secure environment variables
2. Use a production WSGI server like Gunicorn
3. Configure proper SSL/TLS certificates
4. Set up database backups
5. Configure logging and monitoring

## License

This project is open source and available under the MIT License.