# Repository Guidelines

## Project Structure & Module Organization
This repository is a PrestaShop-based monolith with customizations.
- Core app code: `classes/`, `controllers/`, `src/`, `config/`, `app/`.
- Back office entry and assets: `iadmin/`.
- Front themes and static assets: `themes/`.
- Extensions and most active custom work: `modules/` (many modules include their own `src/`, `tests/`, `composer.json`, and/or `package.json`).
- Overrides: `override/` (use only when module/hooks cannot solve the change).
- Runtime artifacts: `var/cache/`, `var/logs/`.

## Build, Test, and Development Commands
There is no root `composer.json` or unified build script; work at module scope.
- `cd modules/<module-name> && composer install` - install PHP dependencies for a module.
- `cd modules/<module-name> && composer test` - run module PHPUnit tests (where defined, e.g. `ps_facetedsearch`).
- `cd modules/<module-name> && composer lint` - run PHP lint/style checks when available.
- `cd modules/<module-name> && npm ci && npm run build` - build JS/CSS for modules with `package.json`.
- `cd modules/<module-name> && npm test` - run frontend/module JS tests when configured.
- `php -l path/to/file.php` - quick syntax check for touched PHP files.
- `Remove-Item var\\cache\\* -Recurse -Force` - clear cache after config/container changes.

## Coding Style & Naming Conventions
- Follow existing PrestaShop conventions: PHP classes in `PascalCase`, methods/properties in `camelCase`, constants in `UPPER_SNAKE_CASE`.
- Use 4-space indentation in PHP and preserve existing module conventions for JS/Vue.
- Prefer PSR-4 namespaces in module `src/` and keep legacy classmap files minimal.
- Avoid editing `vendor/` or generated/minified files unless explicitly required.

## Testing Guidelines
- Put tests in module-local paths like `modules/<module>/tests/php` or `tests/UI`.
- Name PHP tests `*Test.php`; JS tests commonly use `*.spec.js`.
- Run only relevant module test/lint suites before PR; include manual smoke checks for storefront and back office flows impacted by the change.

## Commit & Pull Request Guidelines
- Commit style in this repo is short imperative summaries, often prefixed (`FIX:`, `UPDATE:`). Keep subject <= 72 chars.
- Recommended format: `<TYPE>: <scope> - <what changed>` (example: `FIX: ps_facetedsearch - correct filter sort order`).
- PRs should include: purpose, affected paths/modules, test steps/results, cache-clear/migration notes, and screenshots for UI/theme changes.
- Link related issue/ticket when available.

## Security & Configuration Tips
- Never commit real credentials or tokens; treat `app/config/parameters.php` and module API keys as sensitive.
- Review `.htaccess`, payment/integration modules, and override logic carefully for security-impacting changes.