# GEMINI.md - BackPRO (SEO Management System)

## Project Overview
**BackPRO** is a custom PHP-based SEO management system designed to automate the management and content generation for a network of WordPress satellite sites. It leverages the WordPress REST API, OpenAI for content generation, and various image APIs (like Freepik) to create and publish SEO-optimized articles.

### Core Technologies
- **Language:** PHP 8.3+ (Strict Types enabled)
- **Framework:** Custom MVC architecture (no external framework like Laravel/Symfony)
- **Database:** MySQL/MariaDB (via PDO)
- **Frontend:** Bootstrap 5, Vanilla CSS/JS, PHP Templates
- **Integrations:**
    - WordPress REST API (via Application Passwords)
    - OpenAI API (GPT models for content)
    - Freepik/Unsplash/Pexels APIs (for images)
    - Semstorm/DataForSeo (for SEO metrics)
- **Dependencies:** Managed via Composer (`guzzlehttp/guzzle`, `phpdotenv`)

---

## Architecture & Structure

The project follows a standard MVC pattern with a clear separation of concerns:

- **`index.php`**: Front Controller - entry point for all web requests.
- **`src/Core/`**: The "engine" of the application.
    - `App.php`: Application bootstrapper.
    - `Router.php`: Maps URLs to controllers (defined in `config/routes.php`).
    - `Model.php`: Base class for database interactions using PDO.
    - `Controller.php`: Base class for all controllers.
    - `Auth.php`: Session-based authentication system.
- **`src/Controllers/`**: Contains application logic (Auth, Dashboard, Sites, Topics, Articles, etc.).
- **`src/Models/`**: Database entity representations.
- **`src/Services/`**: External API clients and complex business logic (e.g., `WordPressService`, `OpenAIService`, `PublisherService`).
- **`templates/`**: PHP-based view templates.
- **`cron/`**: Scripts designed for CLI execution via system cron jobs (automated publishing).
- **`migrations/`**: SQL files for database schema evolution.

---

## Development Guidelines

### 1. Coding Standards
- **Naming:** Follow PSR-4 for class autoloading (Namespace `App\` maps to `src/`).
- **Database:** Always use Prepared Statements via `src/Core/Database.php` or `src/Core/Model.php` to prevent SQL Injection.
- **Security:** 
    - Use `htmlspecialchars()` in templates for XSS protection.
    - Passwords must be hashed using `bcrypt` (via `password_hash`).
    - API keys and sensitive data belong in the `.env` file.
- **Error Handling:** Use `App\Helpers\Logger` for logging application events and errors. Logs are stored in `storage/logs/`.

### 2. Working with Models
Models extend `App\Core\Model` and should contain methods for specific data retrieval. Use `$this->db` (a PDO instance) for queries.

### 3. Adding Routes
New endpoints must be registered in `config/routes.php`. Format: `$router->METHOD('/path', 'ControllerName', 'methodName')`.

### 4. Integration Logic
Place logic for interacting with external services in the `src/Services/` directory. These should be designed as reusable components.

---

## Deployment & Running

### Environment Setup
1. **PHP:** Ensure PHP 8.1+ is installed.
2. **Composer:** Run `composer install` to install dependencies.
3. **Configuration:** Copy `.env.example` to `.env` and fill in:
    - Database credentials (`DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS`)
    - API Keys (`OPENAI_API_KEY`, `FREEPIK_API_KEY`, etc.)
4. **Database:** Execute SQL scripts from the `migrations/` directory in order.

### Commands & Scripts
- **Web Interface:** Accessible via a web server pointing to the root directory (ensure `.htaccess` is respected).
- **Automation (CRON):** 
    - `php cron/publish.php` - Triggers the automated publishing cycle.
    - `php cron/semstorm.php` - Syncs SEO metrics.

---

## Key Features
- **WordPress Site CRUD:** Add and manage WP instances.
- **Topic Balancer:** Ensures content is distributed evenly across assigned topics.
- **AI Content Engine:** Generates unique articles with contextual images.
- **Remote Installer:** Automates the installation of WordPress and themes on remote servers.
- **SEO Analytics:** Tracks visibility and indexing status via third-party services.