============================================================
MailFlow - Email Marketing & Automation System
README - Technical Documentation
============================================================

VERSION: 1.0.0
PHP REQUIRED: PHP 8.0+
DATABASE: MySQL 5.7+ or MariaDB 10.3+

------------------------------------------------------------
WHAT IS MAILFLOW?
------------------------------------------------------------
MailFlow is a multi-user email marketing SaaS application.
Each user:
  - Configures their OWN SMTP server credentials
  - Manages their OWN contacts and tags
  - Creates and sends their OWN campaigns
  - Builds their OWN email automations
  - Never sees other users' data

Features:
  - Contact management with tags and filtering
  - CSV import of contacts
  - Email campaigns with scheduling
  - Email queue system with batch processing
  - Automation builder (trigger + action steps with delays)
  - Merge tags ({{first_name}}, {{last_name}}, {{email}}, {{full_name}})
  - SMTP test tool
  - Bulk contact actions

------------------------------------------------------------
PHP EXTENSIONS REQUIRED
------------------------------------------------------------
- PDO (for database)
- PDO_MySQL (MySQL driver)
- json (enabled by default in PHP 8)
- fsockopen / sockets (for SMTP sending - usually enabled)

Check your PHP info: Create a file called phpinfo.php with:
  <?php phpinfo(); ?>
Upload it, visit it in browser, then delete it.

------------------------------------------------------------
DIRECTORY STRUCTURE
------------------------------------------------------------
/ (root - all files go here)
  config.php          - App configuration and DB credentials
  index.php           - Dashboard (protected)
  contacts.php        - Contact list with search/filter/bulk actions
  contact_edit.php    - Add or edit a single contact
  contact_delete.php  - Deletes a contact (called by links)
  contact_import.php  - Import contacts from CSV file
  tags.php            - Create, edit, delete tags
  campaigns.php       - List all campaigns
  campaign_edit.php   - Create or edit a campaign
  campaign_send.php   - Send or schedule a campaign
  queue.php           - View and process the email queue
  automations.php     - List all automations
  automation_edit.php - Create or edit an automation
  settings.php        - SMTP configuration per user
  database.sql        - SQL file to create all database tables

  includes/
    db.php            - Database PDO connection factory
    functions.php     - All shared PHP helper functions
    header.php        - HTML header + sidebar navigation
    footer.php        - HTML footer + CDN scripts

  api/
    process_queue.php - Cron-callable queue processor

  css/
    style.css         - All application styles

  js/
    app.js            - Shared JavaScript utilities

  -- SUPPLIED BY THE SYSTEM (do not create/modify) --
  protect.php         - Checks if user is logged in, sets $userid
  user-lib.php        - User authentication library
  login.php           - Login page
  logout.php          - Logout script
  register.php        - Registration page

------------------------------------------------------------
FILE-BY-FILE CODE EXPLANATION
------------------------------------------------------------

config.php:
  - Sets database connection constants (USER_DB_HOST, USER_DB_NAME, etc.)
  - Sets admin user/password variables
  - Sets QUEUE_BATCH_SIZE (how many emails to process per run, default 20)
  - Sets APP_NAME and APP_VERSION

includes/db.php:
  - Contains get_db() function
  - Creates a singleton PDO connection using config.php constants
  - Uses utf8mb4 charset, exception error mode
  - Returns the same connection object on every call

includes/functions.php:
  - clean($input) - sanitizes user input (htmlspecialchars + trim)
  - safeOut($data) - safely echoes any type of data
  - set_flash($type, $msg) / get_flash() - session-based one-time messages
  - get_smtp_settings($user_id) - retrieves a user's SMTP config from DB
  - send_smtp_email($smtp, $to, $name, $subject, $html, $text) - sends via raw socket SMTP
  - get_user_tags($user_id) - all tags for a user
  - get_contact_tags($contact_id, $user_id) - tags on a specific contact
  - assign_tag_to_contact($contact_id, $tag_id, $user_id) - adds tag and fires automations
  - remove_tag_from_contact($contact_id, $tag_id, $user_id) - removes tag and fires automations
  - fire_automation_trigger($trigger_type, $trigger_value, $contact_id, $user_id) - finds matching automations
  - queue_automation_steps($automation_id, $contact_id, $user_id) - puts automation steps in queue
  - process_automation_queue($user_id) - executes pending automation steps
  - replace_merge_tags($text, $contact) - replaces {{first_name}} etc in email content
  - process_email_queue($user_id) - sends a batch of queued emails
  - get_dashboard_stats($user_id) - returns stats array for dashboard

includes/header.php:
  - Loads all CDN resources (Bootstrap, FontAwesome, Google Fonts)
  - Renders sidebar navigation with active page highlighting
  - Starts the main content area
  - Calls get_flash() to show any flash messages

includes/footer.php:
  - Closes the main content divs
  - Loads jQuery, Bootstrap JS, app.js
  - Renders $extra_js if set on a page

js/app.js:
  - insertAtCursor() - helper to insert merge tags at cursor position in textarea
  - Auto-dismiss alerts after 5 seconds
  - Merge tag click handler (click code to insert into body)
  - Confirm delete links (.confirm-delete class)
  - Select all contacts checkbox handler
  - Step type change handler (show/hide relevant fields)
  - removeStep() - removes an automation step card
  - reNumberSteps() - re-numbers step cards after removal

css/style.css:
  - Full app stylesheet
  - Clean minimal design: white background, one blue accent (#4f8ef7)
  - Sidebar, top bar, stat cards, tables, forms, badges
  - Automation step cards, merge tag helper, status pills

index.php:
  - Dashboard page
  - Shows 6 stat cards (contacts, campaigns, sent, queued, automations, tags)
  - Recent campaigns table
  - Quick action links

contacts.php:
  - Lists contacts with pagination (25 per page)
  - Search by name/email, filter by tag, filter by status
  - Bulk actions: activate, unsubscribe, delete
  - Shows tags for each contact

contact_edit.php:
  - Add/Edit contact form
  - Validates email format and checks for duplicates within user's contacts
  - Tag assignment checkboxes
  - On create: fires contact_created automations

contact_delete.php:
  - Deletes contact and their tag assignments
  - Redirects back to contacts.php

contact_import.php:
  - CSV file upload (max 5MB)
  - Expects header row with 'email', 'first_name', 'last_name' columns
  - Skips duplicates and invalid emails
  - Option to assign tags to all imported contacts
  - Fires contact_created automation for each new contact

tags.php:
  - List, create, edit, delete tags
  - Shows contact count per tag
  - Color picker for tag color

campaigns.php:
  - List all campaigns with status, sent count
  - Delete and duplicate campaigns
  - Link to send/schedule

campaign_edit.php:
  - Create/edit campaign
  - Tag filter for recipients (leave empty = send to all active)
  - HTML body textarea with merge tag helper
  - Saves as 'draft' status

campaign_send.php:
  - Preview of campaign and recipient count
  - Send immediately or schedule for later
  - Queues emails into email_queue table
  - Sets campaign status to 'sending' or 'scheduled'

queue.php:
  - Dashboard showing queue stats (pending/sent/failed/skipped)
  - Manual "Process Queue Now" button
  - Manual "Run Automations" button
  - Shows last 50 queue items with filter
  - Shows cron job URL
  - Clear failed emails button

automations.php:
  - List all automations with trigger, step count, status
  - Toggle active/inactive
  - Delete

automation_edit.php:
  - Trigger selection: Tag Added, Tag Removed, Contact Created
  - Tag selector for tag-based triggers
  - Dynamic step builder with JavaScript
  - Step types: Send Email, Add Tag, Remove Tag, Wait (hours)
  - Saves steps with JSON config

settings.php:
  - SMTP host, port, username, password, encryption
  - Default from name and email
  - Test email sender (uses saved settings to send a test)
  - Common SMTP reference table

api/process_queue.php:
  - Protected by secret key query parameter (?key=...)
  - Processes email queue and automation queue for ALL users
  - Designed for cron job or URL-based automation
  - Returns plain text log output

database.sql:
  - All CREATE TABLE statements
  - No sample data
  - No CREATE DATABASE or USE statements
  - Import via phpMyAdmin

------------------------------------------------------------
INITIAL CONFIGURATION STEPS
------------------------------------------------------------

1. Upload all files to your web server
2. Create a MySQL database via your control panel
3. Import database.sql via phpMyAdmin
4. Edit config.php and set:
   - USER_DB_HOST (usually 'localhost')
   - USER_DB_NAME (your database name)
   - USER_DB_USER (your database username)
   - USER_DB_PASSWORD (your database password)
   - QUEUE_BATCH_SIZE (default 20, increase for high volume)
5. Optional: Add this line to config.php for the cron key:
   define('QUEUE_SECRET_KEY', 'your-secret-key-here');
6. Upload the protect.php, user-lib.php, login.php, logout.php, register.php files
7. Visit your site and register/login
8. Go to SMTP Settings and enter your SMTP credentials
9. Test the connection with the Test Email tool
10. Add contacts, create campaigns, build automations

------------------------------------------------------------
SETTING UP THE CRON JOB
------------------------------------------------------------
To automatically process the queue every 5 minutes, set up a cron job.
Most control panels (cPanel, Plesk) have a "Cron Jobs" section.

Cron command:
  curl -s "https://yourdomain.com/yourdir/api/process_queue.php?key=your-secret-key-here" > /dev/null 2>&1

Or via wget:
  wget -q "https://yourdomain.com/yourdir/api/process_queue.php?key=your-secret-key-here" -O /dev/null

Set the QUEUE_SECRET_KEY constant in config.php to match.

Without a cron job, you can manually process the queue by clicking
"Process Queue Now" on the Queue page, or by visiting the URL above.

------------------------------------------------------------
CDN RESOURCES USED
------------------------------------------------------------

1. Bootstrap 5.3.0 (CSS + JS)
   URL: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/
   Purpose: Responsive grid layout, modals, forms, utility classes.
   Loaded in: header.php (CSS), footer.php (JS bundle)

2. Font Awesome 6.4.0
   URL: https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css
   Purpose: All UI icons throughout the application.
   Loaded in: header.php

3. Google Fonts - Inter
   URL: https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600
   Purpose: Clean, modern sans-serif font for all UI text.
   Loaded in: header.php

4. jQuery 3.7.1
   URL: https://code.jquery.com/jquery-3.7.1.min.js
   Purpose: DOM manipulation, AJAX, event handling.
   Loaded in: footer.php (before app.js)

NOTE: No SRI (Subresource Integrity) attributes are used on any CDN links.

------------------------------------------------------------
DEBUGGING
------------------------------------------------------------

Common issues:

1. "Database connection failed"
   - Check config.php has correct DB_HOST, DB_NAME, DB_USER, DB_PASSWORD
   - Verify the database exists in your control panel
   - Check the database user has full privileges on the database

2. "Contact not found" after login
   - Ensure protect.php is uploaded and working
   - Check that $userid is being set correctly by protect.php

3. Emails not sending
   - Go to Settings > Send a test email and check the error message
   - Verify your SMTP host/port/credentials
   - For Gmail: use App Password, not regular password (requires 2FA)
   - Try port 465 with SSL if port 587 TLS fails
   - Check your server has fsockopen enabled (see phpinfo.php)
   - Check if your server blocks outbound port 587 (ask your host)

4. Queue not processing automatically
   - Verify cron job is set up correctly
   - Test the URL manually in your browser with the ?key= parameter
   - Check the cron job is running as the correct user
   - Add error logging: tail -f /var/log/cron

5. Automations not firing
   - Click "Run Automations" on the Queue page manually
   - Check automation is set to "Active"
   - Verify the trigger condition (correct tag, etc.)

6. White page / PHP error
   - Add these lines temporarily at top of index.php (remove after debugging):
     ini_set('display_errors', 1);
     error_reporting(E_ALL);

7. Redirect loops / "protect.php not found"
   - Ensure protect.php is in the ROOT directory of the app

------------------------------------------------------------
HOW TO EXTEND THE CODEBASE
------------------------------------------------------------

Adding a new protected page:
1. Create yourpage.php in the root
2. Start with:
   require_once('protect.php');
   require_once('config.php');
   require_once('includes/db.php');
   require_once('includes/functions.php');
3. Set $page_title = 'Your Page';
4. Always scope DB queries with WHERE user_id = :uid using $userid
5. Include header: include 'includes/header.php';
6. Your content here
7. Include footer: include 'includes/footer.php';
8. Add a link to it in includes/header.php sidebar

Adding a new automation trigger:
1. Add it to the $valid_triggers array in automation_edit.php
2. Add a label in $trigger_labels on automations.php
3. Add an option in the trigger_type select on automation_edit.php
4. In functions.php fire_automation_trigger(), the trigger_type and value
   are matched against the automations table - no extra code needed
5. Call fire_automation_trigger('your_trigger', 'value', $contact_id, $userid)
   wherever the trigger event occurs in your code

Adding a new automation step type:
1. Add to $valid_step_types array in automation_edit.php
2. Add the HTML fields in automation_edit.php (both saved steps and the JS addStep() function)
3. Add a case in process_automation_queue() in functions.php
4. Handle the step config extraction and action

Adding a new merge tag:
1. In functions.php, add to the $replacements array in replace_merge_tags()
2. Add a <code> element in the merge-tags-help divs in campaign_edit.php and automation_edit.php

============================================================