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