Facebook Leads Integration Module - File Structure
===================================================

modules/facebook_leads_integration/
│
├── facebook_leads_integration.php     # Main module file (hooks, activation, menu)
├── install.php                        # Installation script (creates tables)
├── uninstall.php                      # Uninstallation script (optional cleanup)
├── .htaccess                          # Security rules for module directory
│
├── controllers/
│   └── Facebook_leads_integration.php # Admin controller (settings, fetch, webhook)
│
├── models/
│   └── Facebook_leads_integration_model.php # Database operations and API logic
│
├── views/
│   ├── settings.php                   # Admin settings page
│   └── logs.php                       # Logs viewer page
│
├── helpers/
│   └── facebook_helper.php            # API functions and utilities
│
├── config/
│   └── config.php                     # Module configuration constants
│
├── cron/
│   └── fetch_facebook_leads.php       # Cron job script for automated fetching
│
├── language/
│   └── english/
│       └── facebook_leads_integration_lang.php # English language file
│
├── logs/                              # Log files directory (auto-created)
│   ├── .htaccess                      # Protect log files from web access
│   ├── README.txt                     # Log directory documentation
│   ├── info_YYYY-MM-DD.log           # Info logs (created dynamically)
│   ├── error_YYYY-MM-DD.log          # Error logs (created dynamically)
│   └── cron.log                       # Cron execution logs (optional)
│
└── Documentation Files:
    ├── README.md                      # Complete module documentation
    ├── INSTALLATION.md                # Detailed installation guide
    ├── QUICK_START.md                 # 15-minute quick start guide
    ├── FAQ.md                         # Frequently asked questions
    ├── CHANGELOG.md                   # Version history and changes
    └── LICENSE.txt                    # License and terms

Database Tables (created on activation):
=========================================

1. {prefix}_facebook_leads_settings
   - Stores module configuration (App ID, tokens, etc.)
   
2. {prefix}_facebook_leads_logs
   - Logs all imported leads with status and data

Key Features per File:
======================

facebook_leads_integration.php:
- Module registration and activation
- Admin menu integration
- Dashboard widget
- Hooks registration

install.php:
- Creates database tables
- Inserts default settings
- Creates "Facebook" lead source
- Sets up logs directory

Facebook_leads_integration.php (Controller):
- Settings page handler
- Test connection feature
- Manual fetch leads
- Webhook endpoint (GET/POST)
- Logs viewer

Facebook_leads_integration_model.php (Model):
- Fetch leads from Facebook API
- Import leads into Perfex CRM
- Duplicate detection
- Field mapping and parsing
- Database operations
- Statistics generation

facebook_helper.php:
- Facebook API request function
- Token management functions
- Field mapping utilities
- Logging functions
- Webhook validation

settings.php (View):
- Configuration form
- Test connection button
- Fetch now button
- Statistics display
- Webhook setup instructions

logs.php (View):
- DataTable with all logs
- Status indicators
- View raw lead data modal
- Link to Perfex leads

fetch_facebook_leads.php (Cron):
- CLI script for scheduled execution
- Respects cron interval
- Error handling and logging
- Bootstrap Perfex environment

Security Features:
==================
✓ .htaccess files protecting sensitive directories
✓ SQL injection prevention (prepared statements)
✓ XSS protection (input sanitization)
✓ CSRF protection (Perfex built-in)
✓ Webhook signature validation
✓ Secure token storage in database
✓ Access control (admin permissions)
✓ File upload restrictions

API Integration:
================
- Facebook Graph API v20.0
- OAuth 2.0 authentication
- Page Access Token support
- Leadgen endpoint integration
- Webhook subscriptions
- Error handling and retry logic

User Interface:
===============
- Clean Bootstrap-based admin UI
- Real-time AJAX operations
- Interactive statistics dashboard
- One-click testing
- Comprehensive logs viewer
- Inline help text

Automation:
===========
- Scheduled cron job execution
- Real-time webhook processing
- Automatic duplicate detection
- Background processing
- Log rotation and cleanup

Extensibility:
==============
- Modular structure (MVC pattern)
- CodeIgniter compatible
- Hook-based architecture
- Customizable field mapping
- Easy to extend and modify

Installation Requirements:
==========================
✓ Perfex CRM 3.0+
✓ PHP 7.2+
✓ MySQL 5.7+ / MariaDB 10.2+
✓ cURL extension
✓ SSL certificate (for webhooks)
✓ Write permissions on logs directory

Total Files: 20+ files
Total Lines: ~3000+ lines of code
Code Quality: Production-ready, commented, secure

