# Laundry Management System - Technical Specification

## System Overview

A comprehensive Laravel-based laundry management system with role-based authentication, dynamic pricing, SMS notifications, and administrative reporting.

## Technology Stack

- **Backend**: Laravel 12.0 (PHP 8.2+)
- **Frontend**: Tailwind CSS 4.0 + Blade Templates
- **Database**: SQLite (development) / MySQL/PostgreSQL (production)
- **Build Tool**: Vite
- **Authentication**: Laravel Breeze with custom roles
- **SMS Integration**: TBD (Twilio/Nexmo/Local provider)

## Database Schema Details

### Core Entities

#### Users Table
- **Purpose**: System users (Admin, Data Entry roles)
- **Key Fields**: role (enum: admin, data_entry), is_active
- **Validation**: Email unique, strong password requirements

#### Customers Table
- **Purpose**: Laundry service customers
- **Key Fields**: full_name (min 2 words), phone (required), email (optional), address (required)
- **Relationships**: Created by users, has many orders
- **Indexing**: phone, email, full_name for search

#### Item Categories & Laundry Items
- **Categories**: Basic, Household, Outerwear, Premium
- **Items**: Configurable per category with base pricing
- **Pricing**: Category-level and item-level pricing support

#### Orders & Order Items
- **Order Workflow**: Created → Processing → Ready → Delivered/Picked Up
- **Pricing Calculation**: Base price + quantity discounts + color separation + packaging
- **Status Tracking**: Full audit trail with user attribution

#### Pricing Rules Engine
- **Rule Types**: quantity_discount, color_separation, packaging_preference, bulk_discount
- **Conditions**: JSON field for flexible rule configuration
- **Priority System**: Higher priority rules applied first

#### SMS System
- **Templates**: Configurable message templates with placeholders
- **Logging**: Full delivery tracking and status monitoring
- **Integration**: Provider-agnostic design for easy switching

## API Endpoints Structure

### Authentication Routes
```
POST /login
POST /logout
POST /register (admin only)
GET /dashboard
```

### Customer Management
```
GET /customers - List with search/pagination
POST /customers - Create new customer
GET /customers/{id} - View customer details
PUT /customers/{id} - Update customer
DELETE /customers/{id} - Soft delete customer
GET /customers/{id}/orders - Customer order history
```

### Order Management
```
GET /orders - List orders with filters
POST /orders - Create new order
GET /orders/{id} - View order details
PUT /orders/{id} - Update order
DELETE /orders/{id} - Cancel order
POST /orders/{id}/status - Update order status
GET /orders/{id}/invoice - Generate invoice
```

### Item & Pricing Management
```
GET /items - List items by category
POST /items - Create item (admin only)
PUT /items/{id} - Update item (admin only)
GET /pricing-rules - List pricing rules
POST /pricing-rules - Create rule (admin only)
PUT /pricing-rules/{id} - Update rule (admin only)
```

### Administrative Routes
```
GET /admin/dashboard - System overview
GET /admin/users - User management
GET /admin/reports - Reporting interface
GET /admin/settings - System configuration
GET /admin/sms-templates - SMS template management
```

## Business Logic Implementation

### Customer Validation Rules
- Full name: Required, minimum 2 words, maximum 100 characters
- Phone: Required, format validation (configurable per region)
- Email: Optional, valid email format when provided
- Address: Required, minimum 10 characters, maximum 500 characters

### Pricing Calculation Algorithm
1. Calculate base price (item price × quantity)
2. Apply quantity discounts (configurable tiers)
3. Add color separation charges if applicable
4. Add packaging preference charges
5. Apply any special promotional rules
6. Calculate final total with any manual adjustments

### Order Status Workflow
1. **Created**: Initial order entry
2. **Processing**: Items being washed/cleaned
3. **Ready**: Items ready for pickup/delivery
4. **Completed**: Order fulfilled and paid
5. **Cancelled**: Order cancelled (with reason)

### SMS Notification Triggers
- Order confirmation (immediate)
- Processing started (configurable delay)
- Ready for pickup (immediate)
- Delivery notification (on status change)
- Payment reminders (configurable schedule)

## Security Implementation

### Authentication & Authorization
- Laravel Breeze for base authentication
- Custom middleware for role-based access
- Session-based authentication with CSRF protection
- Password reset functionality with email verification

### Data Protection
- Input validation and sanitization
- SQL injection prevention (Eloquent ORM)
- XSS protection (Blade templating)
- File upload restrictions and validation
- Rate limiting on API endpoints

### Audit Trail
- User action logging for sensitive operations
- Order status change tracking
- Price modification history
- SMS delivery logging

## Performance Considerations

### Database Optimization
- Proper indexing on search fields
- Foreign key constraints for data integrity
- Soft deletes for data retention
- Query optimization with eager loading

### Caching Strategy
- Configuration caching for pricing rules
- View caching for reports
- Session caching for user data
- Database query caching for frequently accessed data

### File Storage
- Local storage for development
- Cloud storage (S3/DigitalOcean) for production
- Image optimization for customer photos
- Backup strategy for critical data

## Testing Strategy

### Unit Tests
- Model validation and relationships
- Pricing calculation logic
- SMS template rendering
- User permission checks

### Feature Tests
- Complete order workflow
- Customer management operations
- Authentication and authorization
- Report generation accuracy

### Integration Tests
- SMS provider integration
- Payment processing (if implemented)
- Email notification system
- Database migration testing

## Deployment Requirements

### Server Requirements
- PHP 8.2+ with required extensions
- MySQL 8.0+ or PostgreSQL 13+
- Redis for caching and sessions
- SSL certificate for HTTPS

### Environment Configuration
- Production environment variables
- Database connection settings
- SMS provider credentials
- Email server configuration
- Backup and monitoring setup

## Future Enhancement Considerations

### Scalability
- Multi-tenant architecture support
- API rate limiting and throttling
- Database sharding for large datasets
- Microservices architecture migration path

### Additional Features
- Mobile app API endpoints
- Payment gateway integration
- Inventory management system
- Customer loyalty program
- Advanced reporting and analytics
