interblue.pl/.paul/codebase/architecture.md

# Architecture

**Analysis Date:** 2026-04-27

## Pattern Overview

**Overall:** PrestaShop 1.7.x MVC Monolith with Hook System and Override Mechanism

**Key Characteristics:**
- Hook-based extensibility (modules register to hooks, PrestaShop fires them)
- Override mechanism (modules replace core classes by copying to `override/`)
- Smarty MVC — controllers prepare data, templates render it
- 133 modules active, many with overrides and custom hooks
- Symfony components embedded (service container, YAML) in PS 1.7 core

## Layers

**Core PrestaShop Layer:**
- Purpose: Framework, models, standard controllers
- Contains: `classes/` (models), `controllers/` (base front/admin), `config/`
- Key entry: `config/config.inc.php`, `config/bootstrap.php`

**Override Layer:**
- Purpose: Replace core classes/controllers without touching core files
- Contains: `override/classes/`, `override/controllers/`, `override/modules/`
- Critical overrides: `override/classes/order/Order.php`, `override/classes/Hook.php`, `override/classes/Dispatcher.php`
- Depends on: Core layer
- Risk: Multiple modules contributing to same override file

**Module Layer:**
- Purpose: Business features, marketplace integrations, shipping, payments
- Contains: `modules/` (133 modules)
- Custom modules: `modules/customfeaturetab/`, `modules/AddOrderExtraFields/`
- Hook registrations in each module's `install()` method
- Depends on: Override layer + Core layer

**Theme Layer:**
- Purpose: Frontend rendering
- Contains: `themes/InterBlue/templates/` (Smarty .tpl)
- Assets: `themes/InterBlue/assets/css/`, `themes/InterBlue/assets/js/`
- Depends on: Module layer (hook output inserted into templates)

**CQRS Extension Layer (src/):**
- Purpose: Modern query handling for Order domain
- Contains: `src/Adapter/Order/QueryHandler/GetOrderForViewingHandler.php`
- Interface: `src/Core/Domain/Order/QueryHandler/GetOrderForViewingHandlerInterface.php`
- Result objects: `src/Core/Domain/Order/QueryResult/`
- Pattern: Adapter bridging legacy PrestaShop to CQRS

## Data Flow

**Frontend HTTP Request:**
1. HTTP request hits `index.php`
2. `Dispatcher` (overridden by fsadvancedurl) matches URL to controller
3. Front controller executes (e.g., `ProductController`)
4. Controller loads model data, fires hooks
5. Smarty renders `.tpl` template with data
6. Module hook outputs inserted at hook positions
7. Response returned

**Order Creation:**
1. Customer submits checkout (via `onepagecheckoutps` — `override/controllers/front/OrderController.php`)
2. `PaymentModule::validateOrder()` called (overridden in `modules/AddOrderExtraFields/override/classes/PaymentModule.php`)
3. `actionBeforeAddOrder` hook fires (`override/classes/order/Order.php` — modrefchange)
4. Order saved to DB with `order_source` field (Allegro/Sklep int./Telefonicznie)
5. `actionBeforeAddOrderInvoice`, `actionBeforeAddDeliveryNumber` hooks fire
6. x13allegro module checks if Allegro order, suppresses customer emails if so

**State Management:**
- Stateless HTTP requests — all state in MySQL database
- Session: PrestaShop cookie-based session
- Cache: Memcached for compiled templates/config

## Key Abstractions

**Module:**
- Purpose: Self-contained feature unit
- Examples: `modules/customfeaturetab/customfeaturetab.php`, `modules/x13allegro/x13allegro.php`
- Pattern: Class extending `Module`, implements `install()`/`uninstall()`, registers hooks

**ObjectModel:**
- Purpose: ORM for PrestaShop database tables
- Examples: `modules/customfeaturetab/classes/CustomFeatureTabRule.php`
- Pattern: Class extending `ObjectModel` with static `$definition` array

**Override:**
- Purpose: Replace core functionality without modifying core files
- Examples: `override/classes/order/Order.php` extends `OrderCore`
- Pattern: `class X extends XCore` in `override/` directory

**Hook:**
- Purpose: Extension point for modules
- Execution intercepted: `override/classes/Hook.php` (cookiesplus GDPR filter)
- Custom hooks: `actionBeforeAddOrder`, `actionBeforeAddOrderInvoice`, `actionBeforeAddDeliveryNumber`

## Entry Points

**Frontend:**
- URL routing: `override/classes/Dispatcher.php` (fsadvancedurl module)
- Product pages: `override/controllers/front/ProductController.php`
- Checkout: `override/controllers/front/OrderController.php` (onepagecheckoutps)

**Admin Panel:**
- URL: `/admin658c34/` (randomized for security)
- Custom admin tabs registered by modules (e.g., "Karty cech produktu")

**Background Scripts:**
- `custom-cron.php` — Scheduled tasks
- `export.php`, `export-csv.php` — Data exports
- `import-products.php` — Bulk product import

## Error Handling

**Strategy:** Mix — PrestaShop global error handler + per-module ad-hoc

**Patterns:**
- Custom modules use minimal error handling
- `die()` calls found in empikmarketplace admin controllers
- No global exception handling in custom modules
- Cache clear required after PHP class changes

## Cross-Cutting Concerns

**Caching:**
- Memcached for compiled Smarty templates and PS config
- LiteSpeed cache module (`modules/litespeedcache/`)
- Manual purge required after changes

**Translation:**
- `$this->l('Text')` in all module PHP files
- Primary locale: Polish (`pl-PL`)
- No separate `.php` language files in custom modules

**Security:**
- Admin URL obfuscation: `admin658c34/`
- Cookie consent: cookiesplus module intercepts Hook execution

---

*Architecture analysis: 2026-04-27*
*Update when major patterns change*