================================================================================
                    BFM PROMO SCHEDULER - PROJECT OVERVIEW
                           (As of May 29, 2026)
================================================================================

PROJECT NAME: BFM Promo Scheduler
FRAMEWORK: Laravel 11 (PHP)
PURPOSE: Automated scheduling and management system for promotional activities

================================================================================
1. WHAT IS THIS PROJECT?
================================================================================

The BFM Promo Scheduler is a web-based application that automates the scheduling
and management of promotional campaigns. It integrates with Shopify to manage:
  • Product Collections
  • Promotional Campaigns
  • Product Pricing
  • Theme Management
  • User Access Control

The system allows users to schedule promotional changes at specific times and
dates, which execute automatically without manual intervention.


================================================================================
2. HOW IT RUNS
================================================================================

TECH STACK:
  • Backend: PHP 8.x with Laravel 11 Framework
  • Frontend: Blade Templates with JavaScript/CSS
  • Database: MySQL/SQLite (managed via migrations)
  • External API: Shopify GraphQL API
  • Package Manager: Composer (PHP), NPM (Node.js)
  • Build Tool: Vite

STARTUP PROCESS:
  1. Run "php artisan serve" to start the development server
  2. Application listens on http://localhost:8000
  3. Users navigate to login page at http://localhost:8000/login
  4. Scheduled tasks execute automatically at configured times via queue system
  5. All Shopify API calls are made via GraphQL endpoint at:
     https://{SHOPIFY_STORE}/admin/api/{API_VERSION}/graphql.json

ENVIRONMENT SETUP:
  • Create .env file with Shopify credentials:
    - SHOPIFY_STORE: Your Shopify store URL
    - SHOPIFY_API_VERSION: API version (e.g., 2024-01)
    - SHOPIFY_ACCESS_TOKEN: Admin API access token
    - DB_CONNECTION: Database driver (sqlite/mysql)
    - APP_KEY: Laravel encryption key


================================================================================
3. CURRENT FEATURES
================================================================================

A. AUTHENTICATION & AUTHORIZATION
   ✓ User login with email and password
   ✓ Role-based access control (Admin vs Regular User)
   ✓ User logout with session invalidation
   ✓ Admin/User dashboard views with different permissions
   ✓ API token-based authentication (foundation)

B. SHOPIFY INTEGRATION
   ✓ Fetch collections from Shopify store
   ✓ Fetch themes from Shopify store
   ✓ Get products by collection
   ✓ Update product information
   ✓ GraphQL API request handling with error logging

C. PROMOTIONAL MANAGEMENT
   ✓ Create and schedule promotional campaigns
   ✓ Set start and end dates/times for promos
   ✓ Track promo status (scheduled, active, expired)
   ✓ Apply promotions to specific products
   ✓ Delete promotional campaigns
   ✓ View user's promotional campaigns
   ✓ Automatic detection of active/expired promos

D. DATA MODELS
   ✓ User model with role management (is_admin field)
   ✓ ScheduledPromo model for managing promotions
   ✓ Eloquent ORM for database interactions
   ✓ Relationships and casts for complex data

E. DATABASE MIGRATIONS
   ✓ Users table (with is_admin field)
   ✓ Scheduled Promos table (with type and user_id fields)
   ✓ Cache and Jobs tables for performance

F. API ENDPOINTS
   POST   /login                              - User authentication
   POST   /logout                             - User logout
   GET    /admin                              - Admin dashboard
   GET    /user                               - User dashboard
   GET    /api/collections                    - Fetch Shopify collections
   GET    /api/themes                         - Fetch Shopify themes
   GET    /api/products-by-collection/{id}    - Get products in collection
   POST   /api/update-product                 - Update product details
   POST   /api/apply-promo                    - Create/apply promotion
   GET    /api/promos                         - Get user's promotions
   DELETE /api/promos/{id}                    - Delete a promotion
   GET    /api/user/{id}                      - Get user details


================================================================================
4. PROJECT STRUCTURE
================================================================================

ROOT DIRECTORIES:
  • app/                     - Application logic (Controllers, Models)
  • config/                  - Configuration files
  • database/                - Migrations, Factories, Seeders
  • resources/               - Views and CSS/JS assets
  • routes/                  - Route definitions
  • storage/                 - Logs and cache files
  • tests/                   - Unit and Feature tests
  • vendor/                  - Composer dependencies
  • bootstrap/               - Framework bootstrap files

KEY FILES:
  • routes/web.php           - Route definitions for web application
  • app/Http/Controllers/ShopifyController.php    - Shopify API integration
  • app/Http/Controllers/AuthController.php       - Authentication logic
  • app/Models/ScheduledPromo.php                 - Promotion data model
  • app/Models/User.php                           - User data model
  • resources/views/admin.blade.php               - Admin dashboard view
  • resources/views/user.blade.php                - User dashboard view
  • resources/views/login.blade.php               - Login page view


================================================================================
5. EDITING INSTRUCTIONS
================================================================================

SCENARIO 1: Adding a New Feature
────────────────────────────────
Step 1: Create a database migration if needed
   Location: database/migrations/
   Command:  php artisan make:migration create_table_name
   Example:  2026_05_29_000000_create_custom_table.php
   Edit:     Add columns in up() method, drop in down() method
   Run:      php artisan migrate

Step 2: Create/Update a Model if needed
   Location: app/Models/
   Template: 
     <?php
     namespace App\Models;
     use Illuminate\Database\Eloquent\Model;
     
     class FeatureName extends Model {
         protected $fillable = ['column1', 'column2'];
         protected $casts = ['data' => 'array'];
     }

Step 3: Create/Update a Controller
   Location: app/Http/Controllers/
   Methods:  index, store, show, update, destroy (standard CRUD)
   Access:   Use Auth::user() for current user information
   Response: return response()->json(['data' => $data]) for API

Step 4: Add Routes
   Location: routes/web.php
   Format:   Route::get('/path', [ControllerName::class, 'methodName'])
   Protection: ->middleware('auth') for protected routes
              ->middleware('admin') for admin-only routes

Step 5: Create Views (if UI needed)
   Location: resources/views/
   Format:   Use Blade templating syntax (@if, @foreach, etc.)
   Styling:  resources/css/app.css
   Scripts:  resources/js/app.js


SCENARIO 2: Modifying Shopify Integration
───────────────────────────────────────────
File to Edit: app/Http/Controllers/ShopifyController.php

The controller has a makeShopifyRequest() method that handles all API calls:
  • Modify GraphQL queries inside the method
  • Add new public methods like: public function getNewData()
  • Update env variables for API credentials (SHOPIFY_STORE, etc.)
  • Check Laravel logs in storage/logs/ for debugging:
    tail -f storage/logs/laravel.log

Example - Adding a new Shopify API method:
  public function getProductDetails($productId)
  {
      $query = '
          query GetProduct($id: ID!) {
            product(id: $id) {
              id
              title
              handle
            }
          }
      ';
      
      $data = $this->makeShopifyRequest($query, ['id' => $productId]);
      return response()->json($data);
  }
  
Then add route: Route::get('/api/product/{id}', [ShopifyController::class, 'getProductDetails']);


SCENARIO 3: Modifying Authentication & User Roles
──────────────────────────────────────────────────
File to Edit: app/Http/Controllers/AuthController.php

To add new roles:
  1. Update Users table migration to add new role columns
  2. Modify AuthController login() method to check roles
  3. Create new middleware in app/Http/Middleware/ if needed
  4. Apply middleware to routes in routes/web.php

Example - Adding role check:
  // In middleware or route
  if (!Auth::user()->is_admin) {
      return redirect('/user');
  }


SCENARIO 4: Modifying Database Schema
──────────────────────────────────────
Files to Edit:
  • database/migrations/YYYY_MM_DD_HHMMSS_description.php
  • app/Models/RelatedModel.php

Process:
  1. Create new migration: php artisan make:migration add_field_to_table
  2. Edit migration file:
     public function up() {
         Schema::table('table_name', function (Blueprint $table) {
             $table->string('new_column')->nullable();
         });
     }
  3. Update Model $fillable array: protected $fillable = [..., 'new_column'];
  4. Run: php artisan migrate
  5. Rollback if needed: php artisan migrate:rollback


SCENARIO 5: Modifying Frontend Views
────────────────────────────────────
Files to Edit:
  • resources/views/*.blade.php
  • resources/css/app.css
  • resources/js/app.js

Blade Syntax:
  • {{ $variable }}              - Echo variable
  • @if ($condition) ... @endif  - Conditional
  • @foreach ($items as $item)   - Loop
  • @csrf                        - CSRF token for forms
  • {{ route('route.name') }}   - Generate URL

Example - Add form to collect data:
  <form action="{{ route('submit') }}" method="POST">
      @csrf
      <input type="text" name="field" required>
      <button type="submit">Submit</button>
  </form>


SCENARIO 6: Testing Changes
───────────────────────────
Location: tests/Feature/ and tests/Unit/

Run tests:
  php artisan test
  php artisan test --filter=TestClassName

Example test file (tests/Feature/PromosTest.php):
  public function test_user_can_create_promo() {
      $response = $this->post('/api/apply-promo', [
          'products' => ['prod_123'],
          'start_datetime' => now()->addDay(),
          'end_datetime' => now()->addDays(7),
      ]);
      $response->assertStatus(200);
  }


SCENARIO 7: Common Commands
───────────────────────────
php artisan migrate              - Run pending migrations
php artisan migrate:refresh      - Refresh all migrations (wipes DB!)
php artisan tinker               - Interactive shell for testing
php artisan queue:work           - Start job queue worker
php artisan serve                - Start development server
php artisan cache:clear          - Clear application cache
npm run dev                       - Start Vite dev server
npm run build                     - Build for production


SCENARIO 8: Adding Database Seeders
───────────────────────────────────
File to Create: database/seeders/CustomSeeder.php

Location: database/seeders/
Template:
  class CustomSeeder extends Seeder {
      public function run(): void {
          DB::table('table_name')->insert([
              ['column1' => 'value1', 'column2' => 'value2'],
          ]);
      }
  }

Register in database/seeders/DatabaseSeeder.php:
  public function run(): void {
      $this->call(CustomSeeder::class);
  }

Run: php artisan db:seed


SCENARIO 9: Environment & Configuration
────────────────────────────────────────
File to Edit: .env (create from .env.example if needed)

Critical Variables:
  APP_NAME=BFM_Promo_Scheduler
  APP_KEY=base64:... (run: php artisan key:generate)
  APP_ENV=local or production
  APP_DEBUG=true or false
  
  SHOPIFY_STORE=mystore.myshopify.com
  SHOPIFY_API_VERSION=2024-01
  SHOPIFY_ACCESS_TOKEN=shpat_...
  
  DB_CONNECTION=sqlite or mysql
  DB_DATABASE=bfm_scheduler (for MySQL)

After changing .env: php artisan cache:clear


SCENARIO 10: Debugging & Logging
────────────────────────────────
Location: storage/logs/laravel.log

Add logging to code:
  use Illuminate\Support\Facades\Log;
  
  Log::info('Message', ['data' => $data]);
  Log::error('Error message', ['exception' => $e]);
  Log::debug('Debug info');

View logs:
  tail -f storage/logs/laravel.log
  
In ShopifyController, logging is already in place for API calls.
Check logs when API requests fail.


================================================================================
6. QUICK REFERENCE - COMMON EDITS CHECKLIST
================================================================================

☐ Add new API endpoint?
  1. Create method in Controller
  2. Add route in routes/web.php
  3. Return JSON response

☐ Add new database field?
  1. Create migration
  2. Update model $fillable array
  3. Run php artisan migrate
  4. Update views if needed

☐ Add new user role?
  1. Add field to User model migration
  2. Update AuthController logic
  3. Create/update middleware
  4. Protect routes with middleware

☐ Change Shopify integration?
  1. Edit ShopifyController.php
  2. Update GraphQL queries as needed
  3. Test in Laravel Tinker or Postman

☐ Update frontend?
  1. Edit .blade.php files
  2. Update CSS in resources/css/app.css
  3. Add JS functionality in resources/js/app.js
  4. Run npm run dev for compilation

☐ Add new model/table?
  1. Create migration: php artisan make:migration
  2. Create model: php artisan make:model ModelName
  3. Define $fillable in model
  4. Create controller if needed
  5. Run migration

☐ Troubleshoot issues?
  1. Check storage/logs/laravel.log
  2. Run: php artisan cache:clear
  3. Run: php artisan config:cache (if config changes)
  4. Verify .env file has all required variables


================================================================================
7. HELPFUL RESOURCES
================================================================================

Laravel Documentation: https://laravel.com/docs/11
Shopify GraphQL API: https://shopify.dev/api/admin-graphql
Blade Template Guide: https://laravel.com/docs/11/views
Eloquent ORM Guide: https://laravel.com/docs/11/eloquent


================================================================================
LAST UPDATED: May 29, 2026
STATUS: Active Development
VERSION: 1.0.0 (Initial Release)
================================================================================