# Repository Guidelines

## Project Structure & Module Organization
adsPRO is a custom PHP MVC app. Keep business logic in:
- `autoload/controls/` (`class.*.php`): request handling (`\controls\*`)
- `autoload/factory/` (`class.*.php`): DB access via Medoo (`\factory\*`)
- `autoload/view/` (`class.*.php`): view composition (`\view\*`)
- `autoload/services/`: external integrations (Google Ads, OpenAI, Claude)
- `templates/`: PHP templates rendered with `\Tpl::view()`
- `migrations/`: SQL migrations (`NNN_description.sql` + optional `demo_data.sql`)
- `layout/`: SCSS/CSS assets (`style.scss` -> `style.css`)

Main entry points are `index.php`, `ajax.php`, `api.php`, `cron.php`, and `install.php`.

## Build, Test, and Development Commands
- `php -S 127.0.0.1:8000` - run a local PHP server from repo root.
- `php install.php` - apply pending DB migrations.
- `php install.php --with_demo` - apply migrations and demo data.
- `php install.php --force` - re-apply tracked migrations.
- `php -l autoload/controls/class.Campaigns.php` - lint a changed PHP file.

There is no dedicated build pipeline; frontend dependencies are committed in `libraries/`. SCSS is typically compiled via VS Code Live Sass Compiler.

## Coding Style & Naming Conventions
- Follow existing PHP style: spaces inside parentheses (`if ( $x )`), braces on new lines.
- Use `PascalCase` class names, lowercase namespaces (`\controls`, `\factory`), and `snake_case` for methods/variables/DB columns.
- Controllers/factories are conventionally `static public function ...`.
- Keep route/module naming aligned with URL pattern `/module/action/...`.

## Testing Guidelines
No first-party automated test suite is maintained in this repo. Validate changes with:
- PHP lint on edited files.
- Manual UI checks for affected `templates/` views.
- Endpoint checks for `ajax.php`, `api.php`, or `cron.php` paths you touched.
- Migration dry run on a non-production database when schema is changed.

Document manual test steps and outcomes in each PR.

## Commit & Pull Request Guidelines
- Use concise Polish commit messages with prefixes seen in history: `feat:`, `fix:`, `update:`.
- Keep commits focused (feature, refactor, migration, UI tweak).
- PRs should include: scope summary, linked issue/task, migration notes, manual test checklist, and screenshots for UI changes.

## Security & Configuration Tips
`config.php` contains environment credentials. Do not introduce new secrets in commits or PR discussions, and treat any credential change as a coordinated ops task.