# Architecture

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

## Pattern Overview

**Overall:** PrestaShop 1.7.8.x MVC e-commerce monolith with hook-based module extensibility and a Symfony admin layer.

**Key Characteristics:**
- Front-office: legacy PrestaShop dispatcher + Smarty templates
- Back-office (admin): Symfony 4-style kernel (`app/AppKernel.php`) at non-standard path `iadmin/`
- Hook-based publish/subscribe extension model — modules attach to named hooks
- Core class overrides via `override/classes/` (monkey-patch layer)
- Multi-domain (`drmaterac.pl` + `lulandia.pl`) served from a single install via `.htaccess` rules

## Layers

**Entry / Routing Layer:**
- Purpose: Route HTTP requests via mod_rewrite to dispatcher / Symfony kernel
- Contains: `.htaccess` (429 lines), `index.php` (front), `iadmin/index.php` (back-office)
- Used by: All HTTP requests
- Key class: `classes/Dispatcher.php` (overridden in `override/classes/Dispatcher.php`)

**Controller Layer:**
- Purpose: Handle request-specific logic (cart, product, checkout, search)
- Contains: `controllers/front/*.php` (CartController, OrderController, ProductController…)
- Base classes: `classes/controller/FrontController.php`, `ModuleFrontController.php`, `AdminController.php`, `ProductListingFrontController.php`
- Overrides: `override/classes/controller/FrontController.php`, `override/classes/controller/ProductListingFrontController.php`

**Model / Domain Layer (ObjectModel):**
- Purpose: ORM-style domain entities (Product, Cart, Order, Customer, Category…)
- Contains: `classes/Product.php`, `classes/Cart.php`, `classes/Order.php`, `classes/Customer.php`, etc.
- Base: `classes/ObjectModel.php`
- Overrides: 31 files in `override/classes/` (e.g. `override/classes/Product.php` adds Google Shopping fields; `override/classes/Cart.php` extends `getOrderTotal()` for ets_promotion pricing)

**Module Layer (extensibility):**
- Purpose: Optional features attached via hooks; first-class extension mechanism
- Contains: `modules/*/` (50+ installed modules, ~138 entries on disk)
- Custom in this project: `modules/crosssellpro/` (Cross Sell PRO carousel), `modules/caraty/`
- Active third-party: `modules/paynow/`, `modules/santandercredit/`, `modules/empikmarketplace/`, `modules/dpdpoland/`, `modules/pdgoogleanalytycs4pro/`, `modules/fbpixel/`, `modules/ekomiratingsandreviews/`, `modules/ceneo_trustedreviews/`, etc.

**Theme / Presentation Layer:**
- Purpose: Page templates and visual assets
- Contains: `themes/leo_gstore/` (active child theme, Leo Gstore v1.4)
- Templates: `themes/leo_gstore/templates/*.tpl` (layout, cart, checkout, product…)
- Per-module overrides: `themes/leo_gstore/modules/<module>/views/templates/hook/*.tpl`
- Assets: `themes/leo_gstore/assets/cache/` (bundled JS/CSS)

**Cross-cutting / Hook System:**
- `classes/Hook.php` + `override/classes/Hook.php` (PageCache module integration)
- Hooks dispatch from controllers/templates → fire each registered module's `hook<Name>()` method
- Registration table: `ps_hook_module`

## Data Flow

**HTTP Request lifecycle (front-office):**

1. Apache receives request → `.htaccess` rewrite rule (line ~353) routes non-physical URLs to `index.php`
2. `Dispatcher::getInstance()->dispatch()` resolves URL to a controller (e.g. `CartController`)
3. Controller `init()` / `initContent()` runs; sets up `Context` (cart, customer, shop, language)
4. Controller dispatches display hooks (`displayHeader`, `displayShoppingCartFooter`, `actionFrontControllerSetMedia`, etc.)
5. Each subscribing module's `hook<Name>()` method runs and may render Smarty partials
6. Smarty renders the theme template (`themes/leo_gstore/templates/cart.tpl`) injecting hook output
7. Response (HTML + CSS + JS) returned to client

**Admin lifecycle:**
- `iadmin/index.php` boots `app/AppKernel.php` (Symfony) — `iadmin/` is the renamed admin folder (security-by-obscurity)
- Symfony routes to controllers; falls back to legacy `Dispatcher` if Symfony routing fails (`iadmin/index.php` line ~93)

**API:**
- `webservice/dispatcher.php` — REST endpoint reached via `.htaccess` line ~323

**State Management:**
- Per-request state held in `classes/Context.php` singleton (`$context->cart`, `$context->customer`, `$context->shop`, `$context->controller`, `$context->language`)
- Persistent state in MySQL (`materac_*` tables)
- Caching configured but disabled (Memcached driver inactive)

## Key Abstractions

**Module:**
- Purpose: Attachable feature unit registering hook callbacks
- Examples: `modules/crosssellpro/crosssellpro.php`, `modules/paynow/paynow.php`, `modules/fbpixel/fbpixel.php`
- Pattern: subclasses `Module` (`classes/Module.php`); `install()` registers hooks; `hook<Name>()` methods are invoked dynamically

**ObjectModel:**
- Purpose: ORM base for domain entities — handles `add()`, `update()`, `delete()`, hydration, validation
- Examples: `classes/Product.php`, `classes/Cart.php`, `classes/Order.php`
- Pattern: declarative `$definition` array describes table + fields

**Hook (publish/subscribe):**
- Purpose: Decouple core from extensions
- Examples: `displayShoppingCartFooter`, `displayCheckoutSummaryTop`, `displayHeader`, `actionFrontControllerSetMedia`
- Pattern: `Hook::exec('hookName', ...)` dispatches; `$module->hookHookName(...)` receives

**Context:**
- Purpose: Per-request global container (cart, customer, shop, language, controller)
- Pattern: Singleton — `Context::getContext()`

**Override:**
- Purpose: Patch core class behavior without editing core
- Examples: `override/classes/Cart.php` (custom totals), `override/classes/Hook.php` (PageCache hooks)
- Pattern: Files in `override/classes/<X>.php` override `classes/<X>.php` via PrestaShop autoloader

## Entry Points

**Front-office:**
- Location: `index.php` (root) — invoked implicitly via `.htaccess`
- Triggers: Any non-physical URL on the public domains
- Responsibilities: Bootstrap → Dispatcher → controller dispatch

**Back-office:**
- Location: `iadmin/index.php` (custom-named admin folder)
- Triggers: Admin URL access
- Responsibilities: Boot `AppKernel`, fall back to legacy dispatcher when needed

**Web service:**
- Location: `webservice/dispatcher.php`
- Triggers: REST API calls

**Custom Cross-Sell module:**
- Location: `modules/crosssellpro/crosssellpro.php`
- Hooks registered (in `install()`): `displayShoppingCartFooter`, `displayCheckoutSummaryTop`, `displayHeader`, `actionFrontControllerSetMedia`
- Key methods: `hookDisplayShoppingCartFooter()`, `hookDisplayCheckoutSummaryTop()`, `buildCrossSellProducts()`, `collectAccessoryIds()`, `getCombinationFlags()`, `presentProducts()`
- Templates: `modules/crosssellpro/views/templates/hook/cartCrossSell.tpl`, `…/checkoutCrossSell.tpl`
- Front assets: `modules/crosssellpro/views/css/cartCrossSell.css`, `modules/crosssellpro/views/js/cartCrossSell.js`

## Error Handling

**Strategy:** PrestaShop legacy approach — `Tools::displayError()`, exceptions logged to `iadmin/errors.log` and `errors.log` (root). Exceptions in hooks may silently degrade module output.

**Patterns:**
- `try/catch` rare in custom code; `import-product.php` lacks transaction wrapping/rollback
- Mail send paths in `buy-by-phone.php` minimally handle PHPMailer failures
- `errors.log` at repo root + `iadmin/errors.log` (5 MB historical) — both inside webroot (concern, see `concerns.md`)

## Cross-Cutting Concerns

**Logging:**
- File-based: `errors.log` (root), `iadmin/errors.log`
- Symfony Monolog wired in admin via `MonologBundle`

**Caching:**
- `pagecache` module
- Memcached configured but disabled (`app/config/parameters.php`)
- Smarty compiled templates: `themes/leo_gstore/cache/`

**Authentication:**
- Customer auth: PrestaShop core (cookies + DB)
- Admin auth: Symfony Security via `iadmin/`

**Image handling:**
- WebP delivery via `.htaccess` content negotiation + `modules/x13webp/`
- Lazy-loading image override (`pshowlazyimg` override)

---

*Architecture analysis: 2026-05-10*
*Update when major patterns change*