# Codebase Structure

**Analysis Date:** 2026-05-10

## Directory Layout

```
drmaterac.pl/
├── index.php                  # Front-office entry (invoked via .htaccess rewrite)
├── .htaccess                  # 429-line rewrite rules (multi-domain routing, SEO redirects)
├── autoload.php               # PSR-4 autoloader bootstrap
├── composer.lock              # PHP dependency lock
├── app/                       # Symfony AppKernel + admin config
│   ├── AppKernel.php          # PrestaShop 1.7.8.11 kernel
│   ├── AppCache.php
│   └── config/                # parameters.php, parameters.yml, config.yml, services/
├── classes/                   # PrestaShop core classes (ObjectModel-based)
│   ├── Product.php, Cart.php, Order.php, Customer.php, …
│   ├── Dispatcher.php, Hook.php, Context.php, ObjectModel.php
│   ├── controller/            # FrontController, AdminController, ModuleFrontController…
│   └── db/, cache/            # Database + caching primitives
├── controllers/               # Page controllers (dispatch targets)
│   ├── front/                 # CartController, OrderController, ProductController…
│   └── admin/                 # Legacy admin (Symfony preferred via iadmin/)
├── modules/                   # All installed modules (~138 entries; 50+ active)
│   ├── crosssellpro/          # CUSTOM — Cross Sell PRO carousel module
│   │   ├── crosssellpro.php
│   │   └── views/{templates/hook,css,js}/
│   ├── caraty/                # CUSTOM — site-specific module
│   ├── paynow/, santandercredit/, ps_checkpayment/, ps_wirepayment/   # Payments
│   ├── empikmarketplace/, dpdpoland/                                  # Marketplace + shipping
│   ├── pdgoogleanalytycs4pro/, fbpixel/, baecommercetracking/         # Analytics
│   ├── ekomiratingsandreviews/, ceneo_trustedreviews/, ekomiSff/      # Reviews
│   └── pagecache/, leo*/, ets_megamenu/, advancedpopupcreator/, …
├── override/                  # Core class overrides (107 files; 31 in override/classes/)
│   └── classes/               # Cart.php, CartRule.php, Product.php, Hook.php, Dispatcher.php,
│                              # FrontController.php, ProductListingFrontController.php …
├── themes/                    # Theme layer
│   ├── leo_gstore/            # ACTIVE child theme (Leo Gstore v1.4)
│   │   ├── templates/         # *.tpl (layout, cart, checkout, product, …)
│   │   ├── modules/           # Per-module template overrides
│   │   ├── assets/cache/      # Pre-bundled JS/CSS
│   │   └── config.xml, config.rb
│   └── _libraries/, classic.zip, leo_gstore.zip
├── config/                    # Bootstrap + Smarty config (NOT app/config/)
│   ├── config.inc.php, defines.inc.php, bootstrap.php
│   └── smarty*.config.inc.php
├── src/                       # Custom PSR-4 namespaced code
│   └── Core/Localization/Locale.php
├── translations/{en,pl}/      # Localization files
├── mails/{en,pl}/             # Email templates
├── js/                        # Global JavaScript (jquery/, date.js)
├── vendor/                    # Composer dependencies
├── webservice/dispatcher.php  # REST API dispatcher
├── iadmin/                    # CUSTOM-NAMED admin folder (5 MB errors.log inside)
│   ├── index.php              # Symfony admin entry
│   ├── backups/, filemanager/, autoupgrade/, api/, export/, import/
│   └── errors.log             # ⚠ committed log (see concerns.md)
├── changelog/                 # Daily Polish changelog markdown files
├── docs/                      # Project docs
├── localization/              # Localization data
├── scripts/, calculate/       # Utility scripts
├── backup_before_patch/       # ⚠ committed *.backup files (see concerns.md)
├── buy-by-phone.php           # Form handler — sends order-by-phone email
├── import-product.php         # 813-line XML feed importer
├── category-description.php   # Category description endpoint
├── diag_*_tmp.php, info.php   # ⚠ diagnostic files (see concerns.md)
└── errors.log                 # PHP error log (committed; should be gitignored)
```

## Directory Purposes

**`classes/`**
- Purpose: PrestaShop core domain layer (ObjectModel + service classes)
- Key files: `Product.php`, `Cart.php`, `Hook.php`, `Dispatcher.php`, `Context.php`, `ObjectModel.php`
- Subdirectories: `controller/` (controller base classes), `db/`, `cache/`

**`controllers/front/`**
- Purpose: Front-office page controllers — dispatch targets matched by URL
- Key files: `CartController.php`, `OrderController.php`, `ProductController.php`, `CategoryController.php`

**`modules/`**
- Purpose: Extension layer — all features beyond core live here as hook-registered modules
- Key custom: `modules/crosssellpro/crosssellpro.php` (cross-sell carousel)
- Key third-party: payment (paynow, santandercredit), shipping (dpdpoland), marketplace (empikmarketplace), analytics (pdgoogleanalytycs4pro, fbpixel), reviews (ekomi*, ceneo_*)

**`modules/crosssellpro/`** — CUSTOM module (Pyziak Jacek)
- `crosssellpro.php` — module class (~335 lines, v1.1.6)
- `views/templates/hook/cartCrossSell.tpl` — cart carousel
- `views/templates/hook/checkoutCrossSell.tpl` — checkout carousel
- `views/css/cartCrossSell.css` — styles (~159 lines)
- `views/js/cartCrossSell.js` — carousel + AJAX add-to-cart (~99 lines)

**`override/classes/`**
- Purpose: Monkey-patch PrestaShop core without editing core
- Key files: `Cart.php`, `CartRule.php`, `Product.php`, `Hook.php`, `Dispatcher.php`, `controller/FrontController.php`, `controller/ProductListingFrontController.php`

**`themes/leo_gstore/`**
- Purpose: Active child theme (`config.xml`)
- Templates: `templates/*.tpl` (page-level), `modules/<module>/views/templates/hook/*.tpl` (module override)
- Assets: pre-bundled in `assets/cache/`

**`app/`**
- Purpose: Symfony kernel + admin config (NOT to be confused with `config/`)
- Key files: `AppKernel.php`, `config/parameters.php` (DB credentials — currently committed), `config/config.yml`

**`config/`**
- Purpose: Legacy PrestaShop bootstrap + Smarty configuration
- Key files: `config.inc.php`, `defines.inc.php`, `bootstrap.php`, `smarty.config.inc.php`

**`iadmin/`**
- Purpose: Renamed back-office (PrestaShop default is `admin/`)
- Note: contains `errors.log` (5 MB), `backups/` (SQL dumps), `autoupgrade/` payload — investigate cleanup

## Key File Locations

**Entry Points:**
- `index.php` — front-office (rewrite target)
- `iadmin/index.php` — back-office (Symfony AppKernel)
- `webservice/dispatcher.php` — REST API

**Configuration:**
- `app/config/parameters.php` — DB / mail / secrets (PHP)
- `app/config/parameters.yml` — Symfony parameters
- `app/config/config.yml` — Symfony service config
- `config/defines.inc.php` — path constants
- `.htaccess` — Apache rewrite rules (multi-domain)

**Core Logic:**
- Custom cross-sell: `modules/crosssellpro/crosssellpro.php`
- Custom site logic: `modules/caraty/caraty.php`
- Domain models: `classes/Product.php`, `classes/Cart.php`, `classes/Order.php`
- Core overrides: `override/classes/`

**Testing:**
- No project-level test suite
- Examples (third-party module tests): `modules/ps_facetedsearch/tests/`, `modules/gamification/tests/`

**Documentation:**
- `AGENTS.md` (root)
- `docs/` (project docs)
- `changelog/YYYY-MM-DD.md` (daily Polish changelog)

## Naming Conventions

**Files:**
- PHP classes: `PascalCase.php` (e.g. `classes/Product.php`)
- Module entry file: lowercase matching directory (`modules/crosssellpro/crosssellpro.php`)
- Smarty templates: `kebab-case.tpl` or `camelCase.tpl` per module (`cartCrossSell.tpl`)
- Asset files: `camelCase.{js,css}` per module
- Templates in theme module overrides: match hook names (`displayShoppingCartFooter.tpl` style not always followed; module-defined name common)

**Directories:**
- Module folders: lowercase, no underscores preferred (`crosssellpro`, `paynow`, `dpdpoland`)
- Snake_case allowed for compound names (`empikmarketplace`, `ets_megamenu`, `leo_gstore`)

**Special Patterns:**
- Module hook handler: `hook<HookNamePascalCase>()` in module class — e.g. `hookDisplayShoppingCartFooter()`
- Hook registration uses camelCase string: `$this->registerHook('displayShoppingCartFooter')`
- Theme module template path: `themes/<theme>/modules/<module>/views/templates/hook/<name>.tpl`

## Where to Add New Code

**New Module / Feature:**
- Primary: `modules/<module-name>/<module-name>.php` (extends `Module`)
- Templates: `modules/<module-name>/views/templates/hook/<hookName>.tpl`
- Theme override: `themes/leo_gstore/modules/<module-name>/views/templates/hook/<hookName>.tpl`
- CSS/JS: `modules/<module-name>/views/css/`, `modules/<module-name>/views/js/`

**Core class extension:**
- Place in `override/classes/<ClassName>.php` extending the core class — NOT inside `classes/`

**New page controller (rare; usually a module):**
- `controllers/front/<Name>Controller.php`

**New translation:**
- `translations/{en,pl}/<context>.{xlf,php}`

**New PSR-4 utility:**
- `src/<Namespace>/<Class>.php` (autoloader configured in `composer.lock`)

## Special Directories

**`backup_before_patch/`**
- Purpose: Manual backup of search engine module pre-patch
- Source: Manual snapshot
- Committed: Yes (should be removed — see `concerns.md`)

**`themes/leo_gstore/cache/`**
- Purpose: Compiled Smarty templates
- Source: Auto-generated at runtime
- Committed: Should be gitignored (verify)

**`iadmin/backups/`**
- Purpose: PrestaShop database backups (e.g. `1698930967-7683b7af.sql.bz2`)
- Committed: Yes (security risk — see `concerns.md`)

---

*Structure analysis: 2026-05-10*
*Update when directory structure changes*