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 SaaS application for managing Google Ads campaigns, products, and clients. It integrates with Google Ads API, OpenAI, and Claude AI to provide AI-powered ad optimization. UI language is Polish.

Architecture

Custom lightweight MVC framework with three layers:

• Controllers (autoload/controls/class.*.php, namespace \controls) - handle requests, return rendered views or JSON
• Factories (autoload/factory/class.*.php, namespace \factory) - data access layer, all static methods, use Medoo ORM
• Views (autoload/view/class.*.php, namespace \view) - compose templates with data
• Services (autoload/services/class.*.php, namespace \services) - external API integrations (GoogleAdsApi, ClaudeApi, OpenAiApi)
• Templates (templates/) - PHP files, variables accessed via $this->varName

Autoloading

PSR-0-like: \controls\Campaigns resolves to autoload/controls/class.Campaigns.php.

Routing

Entry point: index.php. URL /module/action/key=value maps to \controls\Module::action(). Route aliases defined in $route_aliases array. Default route: campaigns/main_view.

Database

MySQL via Medoo ORM (global $mdb). Common patterns:

$mdb->select('table', '*', ['field' => $value]);
$mdb->get('table', '*', ['id' => $id]);
$mdb->insert('table', ['field' => $value]);
$mdb->update('table', ['field' => $value], ['id' => $id]);
$mdb->query($sql, [':param' => $value])->fetchAll(\PDO::FETCH_ASSOC);

Key Utility Classes

• \S - static helpers: \S::get('param') (POST/GET), \S::get_session(), \S::set_session(), \S::alert(), \S::send_email()
• \Tpl::view('path/template', ['var' => $data]) - template rendering
• \Html::input(), \Html::select(), etc. - form component builders
• \Cache::store(), \Cache::fetch() - file-based caching

Authentication

Session-based with cookie auto-login. User stored in $_SESSION['user']. Public paths whitelisted in index.php. IP validated per session.

Commands

Database Migrations

# Run migrations (via browser or CLI)
php install.php

# With demo data
php install.php --with_demo

# Force re-run all
php install.php --force

Migration files in migrations/ follow pattern NNN_description.sql. Tracked in schema_migrations table (idempotent).

SASS Compilation

VS Code Live Sass Compiler watches layout/style.scss and compiles to layout/style.css (compressed).

Deployment

Files auto-upload to remote server via VS Code FTP-Kr extension (.vscode/ftp-kr.json). No build step required.

Code Conventions

• PHP style: Spaces inside parentheses if ( $x ), braces on new line, 2-space indent in templates, 4-space in classes
• Naming: Classes PascalCase, methods/variables/columns snake_case, namespaces lowercase
• Static methods: Controllers and factories use static public function
• JSON endpoints: echo json_encode([...]); exit;
• Template variables: passed as array to \Tpl::view(), accessed as $this->varName

Frontend Stack

jQuery 3.6, DataTables 2.1, Bootstrap 4, Select2 4.1, Highcharts, Font Awesome 6.5, jquery-confirm for modals. All loaded via CDN or from libraries/.

Entry Points

File	Purpose
index.php	Main app (routing + auth)
ajax.php	AJAX requests (authenticated)
api.php	Public API
cron.php	Background jobs
install.php	Database migration runner
config.php	DB and email credentials

API Settings Storage

Google Ads, Claude, and OpenAI API keys are stored in the settings table (key-value) and managed via the Settings page (\controls\Users::settings).

Project Memory

Plik docs/memory.md zawiera trwala pamiec projektu - decyzje, ustalenia i wzorce potwierdzone w trakcie pracy. Czytaj go na poczatku sesji i aktualizuj gdy zapadna nowe istotne decyzje.