adsPRO/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

adsPRO is a PHP web application for managing Google Ads, Facebook Ads, and Google Merchant Center campaigns. It tracks campaign performance (ROAS, budgets, conversions), manages product feeds, and provides AI-powered suggestions for product titles/descriptions. The UI is in Polish.

Tech Stack

• PHP (no framework, custom MVC-like architecture)
• MySQL via Medoo ORM ($mdb global) and RedBeanPHP (\R::) in legacy endpoints
• Frontend: jQuery, DataTables, Highcharts, Select2, Bootstrap 5, Font Awesome 6
• SCSS for styling (layout/style.scss → layout/style.css)
• Google Ads REST API v23 (direct cURL, no SDK)
• Facebook Ads Graph API (direct cURL)
• AI services: OpenAI, Claude, Gemini APIs for product text suggestions

Architecture

Request Flow

index.php is the single entry point. .htaccess rewrites all non-static requests to it. The router uses a $route_aliases map and fallback URL segment parsing (/module/action) to set $_GET['module'] and $_GET['action']. \controls\Site::route() instantiates \controls\{Module} and calls the action method.

Other entry points:

• ajax.php — AJAX requests (same autoloader, session-based auth with IP binding)
• api.php — external API endpoints (domain tester, Open Page Rank)
• cron.php — legacy cron (task reminders, recurring tasks)

Autoloader & Namespace Convention

spl_autoload_register maps namespaces to filesystem paths:

• \controls\Campaigns → autoload/controls/class.Campaigns.php
• \factory\Clients → autoload/factory/class.Clients.php
• \services\GoogleAdsApi → autoload/services/class.GoogleAdsApi.php
• \view\Site → autoload/view/class.Site.php

File naming: class.{ClassName}.php. Root-level classes (no namespace): autoload/class.{Name}.php.

Layer Responsibilities

• autoload/controls/ — Controllers. Handle request params via \S::get(), call factory/services, return HTML (via \Tpl::view()) or echo json_encode() + exit for AJAX.
• autoload/factory/ — Data access layer. Static methods wrapping $mdb queries. Named after domain entities (Clients, Campaigns, Products, etc.).
• autoload/services/ — External API integrations (GoogleAdsApi, FacebookAdsApi, ClaudeApi, OpenAiApi, GeminiApi, SupplementalFeed).
• autoload/view/ — View helpers. Thin wrappers that call \Tpl::view() with template path and data.
• templates/{module}/ — PHP template files rendered by Tpl::view(). Templates access data via $this->varName.

Key Base Classes

• \S — Static utility: get() reads POST/GET, get_session()/set_session() for sessions, alert() for flash messages, send_email() for SMTP.
• \Tpl — Template engine. Tpl::view('module/template', [...]) renders templates/module/template.php. Looks in templates_user/ first (override), then templates/.
• \DbModel — Active Record base class. Subclasses set $table; provides save(), delete().
• \Cache — File-based cache in temp/ directory. Cache::store($key, $data, $ttl) / Cache::fetch($key).

Settings Storage

App settings (API keys, cron state, feature flags) are stored in a settings DB table as key-value pairs. Access via \services\GoogleAdsApi::get_setting($key) / set_setting($key, $value) — these are used globally, not just for Google Ads.

Database Migrations

Numbered SQL files in migrations/ (e.g., 001_google_ads_settings.sql). Run via:

php install.php                    # apply pending migrations
php install.php --force            # re-apply all migrations
php install.php --with_demo        # include demo_data.sql

Tracks applied migrations in schema_migrations table.

Cron System

Multiple cron endpoints called externally (e.g., every 1-5 minutes):

Endpoint	Purpose
/cron.php	Legacy: task reminders, recurring tasks
/cron/cron_universal	Google Ads campaigns + products sync (backfill window)
/cron/cron_campaigns_product_alerts_merchant	Product alerts from Merchant Center
/cron/cron_products_urls	Fetch product URLs from Merchant Center
/cron/cron_facebook_ads	Facebook Ads sync (30-day window)

Progress is tracked in cron_sync_status table with phases (pending → fetch → aggregate_30 → done). Dashboard at /settings shows real-time progress with ETA calculations.

Supplemental Feeds

\services\SupplementalFeed::generate_for_client($id) generates TSV files in feeds/ directory (e.g., feeds/supplemental_1.tsv) for Google Merchant Center. Managed via /feeds UI.

Coding Conventions

• All classes use static methods extensively
• Database access uses the global $mdb (Medoo instance) — never instantiate a new connection
• AJAX endpoints: echo json_encode([...]) then exit
• Page actions: return HTML string from \Tpl::view()
• POST/GET params: always use \S::get('param_name'), never $_POST/$_GET directly
• Flash messages: \S::alert('message') then header('Location: ...') + exit
• Timezone: Europe/Warsaw
• Currency display: \S::number_display($value) formats as "1 234,56 zł"
• All user-facing strings are in Polish

Adding a New Module

1. Create controller: autoload/controls/class.{ModuleName}.php (namespace controls)
2. Create factory: autoload/factory/class.{ModuleName}.php (namespace factory)
3. Optionally create view helper: autoload/view/class.{ModuleName}.php (namespace view)
4. Create templates: templates/{module_name}/main_view.php etc.
5. Add route aliases in index.php $route_aliases array if clean URLs are needed
6. Add sidebar link in templates/site/layout-logged.php

Frontend Libraries (in libraries/)

• medoo/ — Medoo PHP database framework (SQL builder)
• rb.php — RedBeanPHP ORM (used in legacy api.php, cron.php)
• phpmailer/ — Email sending
• framework/ — jQuery UI, Bootstrap, various jQuery plugins
• functions.js — Shared JS utilities
• adspro-dialog.js/.css — Custom modal dialog component