# BFM Promo Scheduler - Documentation ## 1. Overview The **BFM Promo Scheduler** is an automated scheduling and management system designed to streamline promotional activities, collection management, and product updates. This system enables users to schedule promotional campaigns, manage product collections, update pricing, and control theme settings without manual intervention at predetermined times. The system operates on a scheduled basis, reducing the need for manual work during early morning hours or weekends. **Purpose**: To automate and simplify the management of promotional content, collections, products, prices, and themes through a centralized API-driven platform. --- ## 2. Objectives - **Eliminate Manual Work During Off-Hours**: Automate scheduling of promotions and updates to avoid manual work at 8 AM or during weekends - **Centralized Management**: Provide a single platform to manage collections, products, prices, and promotional campaigns - **Efficiency**: Reduce repetitive manual tasks and improve operational efficiency - **Flexibility**: Allow users to schedule updates at any time and have them execute automatically at specified times - **Theme Customization**: Enable dynamic theme changes through automated processes - **API-Driven Architecture**: Leverage RESTful APIs for seamless integration and management --- ## 3. Scope ### Included Features - **Collection Management**: Create, read, update, and delete product collections - **Product Management**: Manage product information and organization - **Pricing Management**: Update and manage product prices - **Promotional Management**: Schedule and manage promotional campaigns and pricing tiers - **Theme Management**: Schedule and apply theme changes - **Scheduled Execution**: Automated execution of scheduled tasks at predetermined times - **User Authentication**: Secure access control for system users - **API Endpoints**: RESTful API for all major operations ### Out of Scope - Real-time manual editing during active promotions - Multi-tenant support (single organization focus) - Advanced analytics and reporting (initial version) --- ## 4. System Users 1. **Administrator**: - Full access to all features - Can manage users and system settings - Can schedule and execute all operations 2. **Marketing Manager**: - Can create and schedule promotional campaigns - Can manage collections and products - Can update prices and promos - Cannot access system-level settings 3. **Content Editor**: - Can view and edit product information - Can schedule content updates - Limited access to pricing and promotional features 4. **System User** (API Consumer): - Can authenticate via API credentials - Can perform assigned operations through API endpoints - Role-based access control applied --- ## 5. Functional Requirements ### 5.1 User Authentication & Authorization - **FR1.1**: System shall support user login with email and password - **FR1.2**: System shall implement role-based access control (RBAC) - **FR1.3**: System shall support API token-based authentication ### 5.2 Collection Management - **FR2.1**: Users shall be able to create new product collections - **FR2.2**: Users shall be able to edit collection names, descriptions, and properties - **FR2.3**: Users shall be able to delete collections - **FR2.4**: Users shall be able to view all collections with filtering options - **FR2.5**: Users shall be able to schedule collection updates ### 5.3 Product Management - **FR3.1**: Users shall be able to add products to collections - **FR3.2**: Users shall be able to update product information (name, description, SKU, etc.) - **FR3.3**: Users shall be able to remove products from collections - **FR3.4**: Users shall be able to view product inventory and status - **FR3.5**: Users shall be able to bulk edit products ### 5.4 Pricing Management - **FR4.1**: Users shall be able to set and update product prices - **FR4.2**: Users shall be able to create and manage price tiers - **FR4.3**: Users shall be able to schedule price changes for future dates and times - **FR4.4**: Users shall be able to view price history and changes ### 5.5 Promotional Management - **FR5.1**: Users shall be able to create promotional campaigns - **FR5.2**: Users shall be able to set promo codes and discount rules - **FR5.3**: Users shall be able to schedule promos to start and end at specific times - **FR5.4**: Users shall be able to apply promotional discounts to products - **FR5.5**: Users shall be able to track active and expired promotions ### 5.6 Theme Management - **FR6.1**: Users shall be able to view available themes - **FR6.2**: Users shall be able to schedule theme changes - **FR6.3**: Users shall be able to apply themes to collections or globally - **FR6.4**: System shall support custom theme creation ### 5.7 Scheduling & Automation - **FR7.1**: System shall execute scheduled tasks at designated times - **FR7.2**: System shall support recurring schedules (daily, weekly, monthly) - **FR7.3**: System shall log all scheduled executions and results - **FR7.4**: System shall support timezone-aware scheduling ### 5.8 API Endpoints - **FR8.1**: RESTful API for all CRUD operations on collections - **FR8.2**: RESTful API for all CRUD operations on products - **FR8.3**: RESTful API for pricing updates and management - **FR8.4**: RESTful API for promotional campaign management - **FR8.5**: RESTful API for theme management - **FR8.6**: RESTful API for schedule management --- ## 6. Non-Functional Requirements ### 6.1 Performance - **NFR1.1**: API endpoints shall respond within 500ms under normal load - **NFR1.2**: System shall support at least 1000 concurrent API requests - **NFR1.3**: Scheduled tasks shall execute within 5 minutes of scheduled time - **NFR1.4**: Database queries shall complete within 2 seconds ### 6.2 Security - **NFR2.1**: All API endpoints shall require authentication - **NFR2.2**: Passwords shall be hashed using bcrypt or similar algorithm - **NFR2.3**: System shall implement HTTPS for all communications - **NFR2.4**: API tokens shall expire after 90 days - **NFR2.5**: System shall log all user actions for audit purposes ### 6.3 Reliability & Availability - **NFR3.1**: System shall maintain 99% uptime during operational hours - **NFR3.2**: System shall implement automatic error recovery for failed scheduled tasks - **NFR3.3**: System shall implement data backup and recovery procedures - **NFR3.4**: Failed tasks shall be retried up to 3 times ### 6.4 Usability - **NFR4.1**: Web interface shall be responsive and mobile-friendly - **NFR4.2**: User interface shall load within 3 seconds - **NFR4.3**: API documentation shall be comprehensive and up-to-date - **NFR4.4**: Error messages shall be clear and actionable ### 6.5 Scalability - **NFR5.1**: System shall support growth to 10,000+ products - **NFR5.2**: System shall support growth to 100+ collections - **NFR5.3**: Database schema shall be optimized for quick queries at scale ### 6.6 Maintainability - **NFR6.1**: Code shall follow PSR-12 PHP coding standards - **NFR6.2**: All functions shall have documentation comments - **NFR6.3**: Unit tests shall cover at least 80% of code - **NFR6.4**: System shall use semantic versioning --- ## 7. System Flow ### 7.1 User Workflow - Scheduling a Promotion ``` 1. User logs into system 2. User navigates to "Promotions" section 3. User creates a new promotion: - Enters promo name, code, and discount rules - Selects products or collections to apply to - Sets discount percentage or fixed amount 4. User schedules promotion: - Selects start date and time - Selects end date and time - Confirms timezone 5. System saves scheduled promotion 6. At scheduled start time, system automatically: - Updates product prices with promotional discounts - Logs the execution 7. At scheduled end time, system automatically: - Restores original prices - Deactivates promotion - Logs the execution 8. User receives notification of promotion execution ``` ### 7.2 System Workflow - Scheduled Task Execution ``` 1. Scheduled task trigger activated 2. System identifies all pending scheduled tasks 3. For each task: - Verify permissions and prerequisites - Execute associated API operations - Log results and timestamps - Update task status 4. If execution fails: - System retries up to 3 times with exponential backoff - Logs failure details - Alerts administrator if critical 5. System generates execution report 6. Cleanup of completed tasks ``` ### 7.3 API Workflow - Update Collection ``` 1. API request received with authentication token 2. System validates token and user permissions 3. System validates request payload 4. If validation passes: - Update collection in database - Log the change - Return success response with updated data 5. If validation fails: - Return error response with details ``` --- ## 8. Validations ### 8.1 User Input Validations - **Email Format**: Must be valid email format (RFC 5322) - **Password**: Minimum 8 characters, must contain uppercase, lowercase, number, and special character - **Product Name**: Required, minimum 3 characters, maximum 255 characters - **Product Price**: Must be positive number, maximum 2 decimal places - **Discount**: Must be between 0-100 for percentages, or positive number for fixed amounts - **Collection Name**: Required, minimum 2 characters, maximum 255 characters - **Dates & Times**: Must be valid ISO 8601 format, future dates for scheduling - **Theme Name**: Must be alphanumeric with hyphens only ### 8.2 Business Logic Validations - **Price Validation**: Promotional price must be less than original price - **Date Validation**: Promotion end date must be after start date - **Inventory Check**: Cannot schedule product updates for out-of-stock items (if applicable) - **Timezone Validation**: Must be a valid IANA timezone identifier - **Duplicate Prevention**: Collection names must be unique - **Deletion Protection**: Cannot delete collections with active promotions ### 8.3 API Response Validations - All responses must include appropriate HTTP status codes - Error responses must include error code and descriptive message - Successful responses must include data payload when applicable - All timestamps must be in ISO 8601 format --- ## 9. Constraints ### 9.1 Technical Constraints - **Language**: PHP 8.1 or higher (Laravel Framework) - **Database**: MySQL 5.7+ or PostgreSQL 12+ - **Server Requirements**: 2GB RAM minimum, 10GB storage minimum - **Browser Support**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+ - **Timezone Handling**: All times stored in UTC, displayed in user's timezone ### 9.2 Operational Constraints - **Scheduled Task Frequency**: Maximum 1000 tasks per day - **API Rate Limiting**: 1000 requests per hour per token - **Concurrent Users**: System designed for up to 50 concurrent users - **Data Retention**: Audit logs retained for 1 year ### 9.3 Business Constraints - **Promotion Overlap**: Multiple promotions can run simultaneously on different products - **Price Adjustment**: Cannot apply promotion with price increase - **Theme Changes**: Limited to 5 theme changes per day to prevent customer confusion - **API Token**: One active token per user at a time ### 9.4 External Constraints - **Network Dependency**: Requires stable internet connection for API operations - **Email Service**: Depends on external email provider for notifications - **Timezone Database**: Depends on IANA timezone database updates --- ## 10. Future Enhancements ### 10.1 Advanced Analytics - **Dashboard with Metrics**: Track promotion performance, sales uplift, customer engagement - **Reporting Engine**: Generate PDF/Excel reports on promotions, sales, and usage - **Data Visualization**: Charts and graphs for performance analysis - **A/B Testing**: Support for testing different promotional strategies ### 10.2 Advanced Scheduling - **Conditional Scheduling**: Execute tasks based on conditions (e.g., if inventory < threshold) - **Event-Triggered Actions**: Trigger actions based on system events - **Workflow Builder**: Visual workflow designer for complex automation sequences - **Machine Learning Optimization**: AI-suggested optimal promotion timing ### 10.3 Multi-Channel Integration - **Social Media Integration**: Post promotions to social media platforms - **Email Campaign Integration**: Automated email notifications for promotions - **SMS Alerts**: Send SMS notifications for flash sales - **Webhook Support**: Integrate with third-party systems ### 10.4 Advanced User Features - **Team Collaboration**: Multi-user project management and approval workflows - **Role Templates**: Pre-configured role templates for common user types - **Audit Trail Dashboard**: Comprehensive audit trail visualization - **User Activity Analytics**: Track user engagement and system usage ### 10.5 Performance & Scalability - **Caching Layer**: Redis caching for frequently accessed data - **Database Replication**: Master-slave database setup for high availability - **Load Balancing**: Multi-server deployment with load balancing - **Microservices Architecture**: Transition to microservices for better scalability ### 10.6 Mobile Application - **Native Mobile App**: iOS and Android applications for mobile management - **Push Notifications**: Real-time notifications for scheduled events - **Offline Mode**: Offline capabilities with sync when online ### 10.7 Advanced Security - **Two-Factor Authentication (2FA)**: Support for authenticator apps and SMS - **IP Whitelisting**: Restrict API access to specific IP addresses - **Encryption**: End-to-end encryption for sensitive data - **OAuth 2.0 Integration**: Support for third-party OAuth providers ### 10.8 Localization & Internationalization - **Multi-Language Support**: Support for multiple languages - **Currency Conversion**: Automatic currency conversion - **Regional Compliance**: GDPR, CCPA, and other regional compliance features ### 10.9 Template & Library Features - **Promotion Templates**: Pre-built templates for common promotions - **Theme Library**: Extended theme library with community themes - **Integration Marketplace**: Community-contributed integrations - **API Versioning**: Support for multiple API versions ### 10.10 Disaster Recovery & Business Continuity - **Automated Backups**: Daily automated backups with point-in-time recovery - **Disaster Recovery Plan**: Documented DRP with regular testing - **Geographic Redundancy**: Backup in geographically distant data center - **SLA Monitoring**: Real-time SLA compliance monitoring and alerts --- ## Document Version - **Version**: 1.0 - **Last Updated**: May 22, 2026 - **Status**: Active - **Author**: Development Team --- ## Appendix - Glossary | Term | Definition | |------|-----------| | **Collection** | A group of related products organized for promotional or organizational purposes | | **Promotion** | A marketing campaign with discount or special offers | | **Promo Code** | A code customers use to redeem promotions | | **Theme** | Visual styling and layout of the system interface | | **API Token** | Authentication credential for API access | | **Scheduled Task** | An operation set to execute at a specific future date and time | | **RBAC** | Role-Based Access Control - permission system based on user roles | | **SKU** | Stock Keeping Unit - unique product identifier | | **UTC** | Coordinated Universal Time - timezone standard | | **Audit Log** | Record of system actions for security and compliance | --- ## Change Log | Version | Date | Changes | |---------|------|---------| | 1.0 | 2026-05-22 | Initial documentation creation |