# Kreme Donuts POS & Inventory System

A comprehensive full-stack Point of Sale (POS) and Inventory Management System for multi-branch bakeries, built with Core PHP, MySQL, JavaScript/AJAX, Bootstrap CSS, and a responsive UI/UX design.

## Features

### 🎯 Core Features
- **Multi-Branch Support** - Manage multiple bakery branches from a single system
- **Walk-in & Online Orders** - Handle both types of orders with separate workflows
- **Real-time Inventory Tracking** - Automatic inventory deduction during order preparation
- **Low-Stock Alerts** - Automatic notifications when ingredients reach minimum threshold
- **Sales Reports** - Daily, monthly, and yearly sales analytics
- **Kitchen Display System** - Tablet-friendly kitchen order management
- **User Roles & Permissions** - Admin, Cashier, Kitchen Staff, Inventory Manager, Social Media Manager

### 🔧 Technical Stack
- **Backend**: PHP 7.4+
- **Database**: MySQL 5.7+
- **Frontend**: HTML5, CSS3, Bootstrap 5
- **Scripting**: Vanilla JavaScript, AJAX
- **UI/UX**: Fully Responsive Design

## Installation

### Prerequisites
- XAMPP (or any PHP server with MySQL support)
- PHP 7.4 or higher
- MySQL 5.7 or higher
- Web Browser (Chrome, Firefox, Safari, Edge)

### Step 1: Clone/Setup the Project

```bash
# Navigate to XAMPP htdocs
cd C:\xampp\htdocs\kreme_donuts

# The project structure is already created
```

### Step 2: Create Database

1. Open phpMyAdmin at `http://localhost/phpmyadmin`
2. Create a new database called `kreme_donuts_db`
3. Navigate to `http://localhost/kreme_donuts/config/init_db.php` to initialize tables

Or execute this SQL:
```sql
CREATE DATABASE kreme_donuts_db;
USE kreme_donuts_db;
```

### Step 3: Start XAMPP

1. Open XAMPP Control Panel
2. Start Apache and MySQL services
3. Access the system at `http://localhost/kreme_donuts/public/login.php`

### Step 4: Login

Use demo credentials:
```
Admin:       admin / admin123
Cashier:     cashier1 / cashier123
Kitchen:     kitchen1 / kitchen123
Inventory:   inventory1 / inventory123
Social Mgr:  social1 / social123
```

## Project Structure

```
kreme_donuts/
├── config/
│   ├── database.php          # Database connection
│   └── init_db.php           # Database initialization
├── app/
│   ├── Auth.php              # Authentication class
│   ├── Order.php             # Order management class
│   ├── Product.php           # Product management class
│   ├── Inventory.php         # Inventory management class
│   └── Report.php            # Reports generation class
├── assets/
│   ├── css/
│   │   └── style.css         # Custom CSS styling
│   └── js/
│       └── main.js           # JavaScript utilities
├── public/
│   ├── login.php             # Login page
│   ├── dashboard.php         # Main dashboard
│   ├── orders.php            # Orders management
│   ├── new_order.php         # Create new order
│   ├── inventory.php         # Inventory management
│   ├── kitchen.php           # Kitchen display system
│   ├── reports.php           # Sales reports
│   ├── products.php          # Product management
│   ├── users.php             # User management
│   ├── low_stock.php         # Low stock alerts
│   ├── online_orders.php     # Online orders management
│   ├── api/
│   │   ├── login.php         # Login API
│   │   ├── logout.php        # Logout API
│   │   ├── get_dashboard.php # Dashboard data
│   │   ├── get_orders.php    # Orders list
│   │   ├── get_order_details.php # Order details
│   │   ├── create_order.php  # Create order
│   │   ├── get_inventory.php # Inventory list
│   │   ├── add_ingredient.php # Add ingredient
│   │   └── restock_ingredient.php # Restock
│   └── SYSTEM_PLAN.MD        # Original system plan
```

## User Roles & Permissions

### Admin
- Full system access
- View all branches data
- Manage users and roles
- Generate reports
- Manage products and ingredients
- Approve inventory adjustments

### Cashier
- Create walk-in orders
- View order status
- Print receipts
- Cannot modify inventory directly

### Kitchen Staff
- View kitchen orders (tablet-friendly display)
- Update order status (Preparing → Done → Ready)
- See special instructions
- Cannot modify inventory

### Inventory Manager
- Manage ingredient stock levels
- Restock ingredients
- View low-stock alerts
- Track inventory history
- Cannot create orders

### Social Media Manager
- Create online orders
- Assign orders to branches
- Notify customers when orders are ready
- Track delivery status

## Order Flow

### Walk-in Orders
1. Cashier enters order in POS
2. Temporary receipt printed (serves as order reference)
3. Order sent to kitchen tablet
4. Kitchen staff prepares order (Status: Preparing)
5. Ingredients automatically deducted
6. Order marked as Done/Ready
7. Customer pays
8. Final receipt printed
9. Order completed

### Online Orders
1. Social Media Manager receives order via social media
2. Encodes order in system
3. Assigns to specific branch
4. Order appears on kitchen tablet
5. Kitchen staff prepares (automatic inventory deduction)
6. Order marked as Done/Ready
7. Awaits customer pickup or delivery
8. Status updates to Completed upon collection
9. Sale automatically recorded

## Inventory Management

### Key Features
- **Automatic Deduction** - Ingredients deducted automatically when orders are prepared
- **Low-Stock Alerts** - Notifications trigger when stock falls below threshold
- **Authorized Restocking** - Only admin/inventory staff can add or adjust stock
- **Complete Audit Trail** - All inventory transactions logged with timestamp and user
- **Stock Value Tracking** - Real-time calculation of total inventory value

### Recipe Configuration
Each product has a recipe that defines:
- Required ingredients
- Quantity needed per product

When an order is placed, system automatically calculates and deducts needed ingredients.

## Sales Reports

### Available Reports
- **Daily Sales** - Today's transactions and totals
- **Monthly Sales** - Product sales, trends, best-sellers
- **Yearly Sales** - Annual performance overview
- **Peak Hours** - Busiest times of day
- **Walk-in vs Online** - Sales comparison by order type
- **Top Products** - Best-selling items
- **Top Customers** - Customer spending analysis

### Export Options
- Export to PDF (for printing)
- Export to Excel (for analysis)
- Download CSV (for data import)

## API Endpoints

### Authentication
- `POST /public/api/login.php` - User login
- `GET /public/api/logout.php` - User logout

### Dashboard
- `GET /public/api/get_dashboard.php` - Dashboard metrics

### Orders
- `GET /public/api/get_orders.php` - List orders with filters
- `GET /public/api/get_order_details.php` - Get specific order
- `POST /public/api/create_order.php` - Create new order

### Inventory
- `GET /public/api/get_inventory.php` - List ingredients
- `POST /public/api/add_ingredient.php` - Add new ingredient
- `POST /public/api/restock_ingredient.php` - Restock ingredient

## Database Schema

### Key Tables
- **users** - User accounts and roles
- **branches** - Multi-branch information
- **products** - Product catalog
- **ingredients** - Inventory items
- **recipe_items** - Product recipes (product-ingredient mapping)
- **orders** - Order transactions
- **order_items** - Order line items
- **inventory_transactions** - Inventory audit trail
- **stock_alerts** - Low-stock notifications

## Security Features

- **Password Hashing** - bcrypt hashing for secure password storage
- **Session Management** - Server-side session handling
- **Role-Based Access Control** - Permission-based page access
- **SQL Prepared Statements** - Protection against SQL injection
- **Input Validation** - Data validation on both client and server
- **CSRF Protection** - Request validation (can be enhanced)

## Responsive Design

The system is fully responsive and works on:
- Desktop (1920px and above)
- Laptop (1024px - 1920px)
- Tablet (768px - 1024px)
- Mobile (320px - 768px)

Perfect for:
- Point-of-Sale terminals
- Kitchen tablets
- Mobile devices for social media managers
- Desktop dashboards for admins

## Features by Screen Size

- **Desktop**: Full feature access, detailed reports, side navigation
- **Tablet**: Touch-optimized buttons, full POS functionality
- **Mobile**: Essential features, simplified navigation, touch-friendly interface

## Configuration

### Database Connection
Edit `config/database.php`:
```php
define('DB_HOST', 'localhost');
define('DB_USER', 'root');
define('DB_PASSWORD', '');
define('DB_NAME', 'kreme_donuts_db');
```

### Session Settings
Edit `config/database.php` to adjust session timeout and other settings.

## Customization

### Adding New Products
1. Go to Products page (Admin only)
2. Click "Add Product"
3. Set price and category
4. Configure recipe (ingredients needed)

### Adding New Users
1. Go to Users page (Admin only)
2. Click "Add User"
3. Assign role and branch
4. Set initial password

### Modifying Reports
Edit `app/Report.php` to customize report generation and filters.

## Troubleshooting

### Database Connection Error
- Ensure MySQL is running
- Check database credentials in `config/database.php`
- Verify database `kreme_donuts_db` exists

### Login Not Working
- Clear browser cookies
- Verify database is initialized
- Check user credentials in database

### Orders Not Showing
- Refresh page
- Check user branch assignment
- Verify order status filters

### Inventory Not Deducting
- Ensure recipe is configured for the product
- Check ingredient minimum_threshold vs current_quantity
- Review inventory transaction logs

## Performance Tips

1. **Regular Backups** - Backup database daily
2. **Archive Old Data** - Archive completed orders monthly
3. **Optimize Queries** - Use appropriate database indexes
4. **Cache Reports** - Consider caching frequently-used reports
5. **Clean Logs** - Archive old transaction logs

## Future Enhancements

- [ ] Payment gateway integration
- [ ] Customer loyalty program
- [ ] Mobile app (React Native)
- [ ] Real-time notifications (WebSocket)
- [ ] Barcode scanning
- [ ] Advanced analytics dashboard
- [ ] Supplier management
- [ ] Price history tracking
- [ ] Multi-language support
- [ ] Dark mode theme

## Support & Maintenance

For issues, updates, or customizations:
1. Review system logs in database
2. Check application error messages
3. Verify user permissions and roles
4. Ensure all required fields are populated

## License

This system is proprietary software for Kreme Donuts. Unauthorized distribution is prohibited.

## Version

**Current Version**: 1.0.0
**Last Updated**: January 31, 2026

---

**Kreme Donuts POS & Inventory System** - Making bakery operations simple and efficient.