# 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
```

## Getting Started

### Prerequisites

- Python 3.8 or higher

### Installation

1. Clone the repository
2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Initialize the database:

```bash
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:

```bash
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/login` - Obtain JWT 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:

```bash
ruff check .
```

### Running Tests

```bash
pytest
```

## License

This project is licensed under the MIT License.