orderPRO/.paul/codebase/ARCHITECTURE.md

# Architecture

**Analysis Date:** 2026-03-12

---

## 1. Directory Structure

```
orderPRO/                          # Project root
├── bin/                           # CLI scripts (cron, migrations, data tools)
├── bootstrap/
│   └── app.php                    # Application bootstrap: autoload, env, config, DI wiring
├── config/
│   ├── app.php                    # Application config (name, debug, locale, paths, cron, secrets)
│   └── database.php               # DB connection params
├── database/
│   ├── migrations/                # SQL migration files (47 files, named YYYYMMDD_NNNNNN_description.sql)
│   └── drafts/                    # Non-active schema drafts
├── DOCS/
│   ├── ARCHITECTURE.md            # Existing architecture notes (Polish, incremental)
│   ├── DB_SCHEMA.md               # Table-level schema reference
│   ├── TECH_CHANGELOG.md          # Chronological technical changelog
│   └── todo.md                    # Work backlog
├── public/
│   ├── index.php                  # Single HTTP entry point
│   └── assets/                    # Compiled CSS, JS, images (served directly)
├── resources/
│   ├── lang/                      # Translation files (PL locale)
│   ├── modules/                   # Frontend JS/CSS modules (e.g. jquery-alerts)
│   ├── scss/                      # SCSS source → compiled to public/assets/css/
│   └── views/                     # PHP template files (plain PHP, no engine)
├── routes/
│   └── web.php                    # All route definitions (returns closure)
├── src/
│   ├── Core/                      # Framework kernel (router, DB, HTTP, security, i18n, views)
│   └── Modules/                   # Feature modules (Auth, Orders, Settings, Cron, Shipments, Users)
├── storage/
│   ├── cache/                     # File cache
│   ├── logs/                      # app.log
│   ├── sessions/                  # PHP session files
│   └── tmp/                       # Temp files (e.g. downloaded labels)
└── tests/
    └── Unit/                      # Unit tests (currently empty)
```

---

## 2. Application Layers

### Layer 1 — Kernel (`src/Core/`)

Framework infrastructure. No business logic.

| Class | File | Responsibility |
|---|---|---|
| `Application` | `src/Core/Application.php` | Root service locator. Wires all dependencies, boots session, registers error handlers, runs cron on web. |
| `Router` | `src/Core/Routing/Router.php` | Pattern-matching router for GET/POST. Supports `{param}` segments and middleware pipeline. |
| `Request` | `src/Core/Http/Request.php` | Immutable wrapper around `$_GET`, `$_POST`, `$_FILES`, `$_SERVER`. |
| `Response` | `src/Core/Http/Response.php` | Fluent response builder (`html()`, `json()`, `redirect()`). |
| `Template` | `src/Core/View/Template.php` | Output-buffer PHP view renderer. Injects `$e()` (XSS escape) and `$t()` (translation) helpers. Supports layout wrapping. |
| `ConnectionFactory` | `src/Core/Database/ConnectionFactory.php` | Creates PDO connection from config array. |
| `Migrator` | `src/Core/Database/Migrator.php` | Applies pending `.sql` files from `database/migrations/`. Uses DB lock (`GET_LOCK`) to prevent concurrent runs. |
| `Csrf` | `src/Core/Security/Csrf.php` | Session-based CSRF token generate/validate using `hash_equals`. |
| `Session` | `src/Core/Support/Session.php` | Thin wrapper around PHP sessions. |
| `Flash` | `src/Core/Support/Flash.php` | Single-request flash messages stored in `$_SESSION`. |
| `Logger` | `src/Core/Support/Logger.php` | Appends `[LEVEL] message {context_json}` lines to `storage/logs/app.log`. |
| `Env` | `src/Core/Support/Env.php` | Parses `.env` file; `get()`, `bool()` helpers. |
| `Translator` | `src/Core/I18n/Translator.php` | Loads language files from `resources/lang/`; `get($key, $replace)`. |

### Layer 2 — Modules (`src/Modules/`)

Feature slices. Each module owns its controllers, repositories and services.

| Module | Path | Active Modules |
|---|---|---|
| Auth | `src/Modules/Auth/` | Login/logout, session-based auth |
| Orders | `src/Modules/Orders/` | Order list/detail, status change, import |
| Settings | `src/Modules/Settings/` | Statuses, integrations (Allegro/Apaczka/InPost/shopPRO), DB, cron, company |
| Cron | `src/Modules/Cron/` | Job scheduling, execution, handlers per job type |
| Shipments | `src/Modules/Shipments/` | Provider-agnostic shipment creation, label download |
| Users | `src/Modules/Users/` | User management (list, create) |

### Layer 3 — Views (`resources/views/`)

Plain PHP templates. No Blade, no Twig.

| Path | Renders for |
|---|---|
| `layouts/app.php` | Main authenticated shell (sidebar nav) |
| `layouts/auth.php` | Login page shell |
| `orders/list.php` | Order list page |
| `orders/show.php` | Order detail page |
| `settings/allegro.php` | Allegro integration settings |
| `settings/apaczka.php` | Apaczka integration settings |
| `settings/inpost.php` | InPost integration settings |
| `settings/shoppro.php` | shopPRO integration settings (multi-instance) |
| `settings/statuses.php` | Status groups & statuses management |
| `settings/cron.php` | Cron scheduler UI |
| `settings/integrations.php` | Integrations hub |
| `settings/database.php` | Migrations UI |
| `settings/company.php` | Company/sender settings |
| `shipments/prepare.php` | Shipment creation form |
| `users/index.php` | Users list |
| `auth/login.php` | Login form |
| `components/table-list.php` | Reusable paginated table component |
| `components/order-status-panel.php` | Reusable order status panel |

---

## 3. Bootstrap and Request Flow

### Bootstrap sequence

```
public/index.php
  └─ bootstrap/app.php
       ├─ autoload (vendor/autoload.php or spl_autoload from src/)
       ├─ Env::load('.env')
       ├─ load config/app.php + config/database.php
       ├─ new Application($basePath, $config)
       │    ├─ new Router
       │    ├─ new Translator
       │    ├─ new Template
       │    ├─ ConnectionFactory::make → PDO
       │    ├─ new UserRepository, OrdersRepository, OrderStatusRepository
       │    ├─ new Migrator
       │    └─ new AuthService, Logger
       └─ $app->boot()
            ├─ prepareDirectories (storage/*)
            ├─ configureSession
            ├─ registerErrorHandlers
            └─ require routes/web.php  →  $routes($app)
                   (instantiates all controllers, repositories, services and registers routes)
```

### Per-request flow

```
HTTP request
  → public/index.php
  → $app->run()
       ├─ Request::capture()         (wraps $_GET/$_POST/$_FILES/$_SERVER)
       ├─ maybeRunCronOnWeb()        (if cron_run_on_web=1, throttled, DB-locked)
       └─ Router::dispatch($request)
            ├─ find route by method + path (exact match first, then {param} patterns)
            ├─ attach URL params to $request via withAttributes()
            ├─ build middleware pipeline (array_reduce, reversed)
            │    └─ AuthMiddleware::handle()   (most routes)
            │         └─ redirect /login if not authenticated
            └─ call controller method($request): Response
                 ├─ reads input via $request->input()
                 ├─ validates CSRF via Csrf::validate()
                 ├─ calls repository/service methods
                 └─ returns Response::html($template->render(...))
                           or Response::redirect(...)
                           or Response::json(...)
  → Response::send()    (sets headers, echoes body)
```

---

## 4. Module Organization

### Auth (`src/Modules/Auth/`)

| Class | Responsibility |
|---|---|
| `AuthController` | `GET /login`, `POST /login`, `POST /logout` |
| `AuthService` | `check()`, `user()`, `attempt(email, password)`, `logout()` backed by session |
| `AuthMiddleware` | `handle(Request, callable $next)` — redirects to `/login` if session unauthenticated |

### Orders (`src/Modules/Orders/`)

| Class | Responsibility |
|---|---|
| `OrdersController` | `index` (list), `show` (detail), `updateStatus` — builds view data, delegates DB to repos |
| `OrdersRepository` | `paginate()`, `findDetails()`, `statusCounts()`, `statusPanelConfig()`, `sourceOptions()`, `updateOrderStatus()`, `recordActivity()` |
| `OrderImportRepository` | `upsertOrderAggregate()` — transactional upsert of the full order aggregate (order + addresses + items + payments + shipments + notes + status history) |

### Settings (`src/Modules/Settings/`)

Large module covering all configuration:

**Controllers:**
- `SettingsController` — statuses, status groups, DB migrations
- `AllegroIntegrationController` — Allegro OAuth2, import, status mappings, delivery mappings
- `ApaczkaIntegrationController` — Apaczka API config
- `InpostIntegrationController` — InPost ShipX config
- `ShopproIntegrationsController` — shopPRO multi-instance management (statuses, delivery, sync)
- `IntegrationsHubController` — overview hub listing all provider instances
- `CronSettingsController` — cron schedule UI
- `CompanySettingsController` — company/sender details

**Repositories:**
- `OrderStatusRepository` — CRUD + reorder for `order_status_groups` and `order_statuses`
- `AllegroIntegrationRepository` — reads/writes `allegro_integration_settings`; encrypts secrets via `IntegrationSecretCipher`
- `AllegroStatusMappingRepository` — `allegro_order_status_mappings` CRUD
- `AllegroOrderSyncStateRepository` — cursor state for Allegro sync (`integration_order_sync_state`)
- `ApaczkaIntegrationRepository` — reads/writes `apaczka_integration_settings`
- `InpostIntegrationRepository` — reads/writes `inpost_integration_settings`
- `IntegrationsRepository` — base `integrations` table queries (hub listing)
- `ShopproIntegrationsRepository` — multi-instance CRUD for `integrations` where `type=shoppro`
- `ShopproStatusMappingRepository` — `order_status_mappings` per shopPRO integration
- `ShopproDeliveryMethodMappingRepository` — `shoppro_delivery_method_mappings`
- `CarrierDeliveryMethodMappingRepository` — `carrier_delivery_method_mappings` (unified, cross-source)
- `CompanySettingsRepository` — `company_settings` single-row config
- `AllegroDeliveryMethodMappingRepository` — Allegro-specific delivery method mappings (legacy, superseded by carrier table)

**API Clients (HTTP adapters):**
- `AllegroOAuthClient` — builds OAuth2 authorize URL, exchanges code for tokens, refreshes tokens
- `AllegroApiClient` — calls Allegro REST API (`/order/checkout-forms`, `/sale/product-offers`, `/delivery-services`, etc.)
- `ApaczkaApiClient` — calls Apaczka REST API (services, create shipment, label, points)
- `ShopproApiClient` — calls shopPRO REST API (orders, products, dictionaries, statuses)

**Services:**
- `AllegroOrderImportService` — maps single Allegro checkout-form to neutral order aggregate, calls `OrderImportRepository::upsertOrderAggregate()`
- `AllegroOrdersSyncService` — paginates Allegro checkout-forms list and imports new/changed orders; maintains sync cursor
- `AllegroStatusSyncService` — syncs statuses between Allegro and orderPRO based on configured direction
- `AllegroStatusDiscoveryService` — fetches live status list from Allegro API and seeds `allegro_order_status_mappings`
- `ShopproOrdersSyncService` — fetches shopPRO orders, maps to neutral aggregate, handles paczkomat/pickup points, media
- `ShopproStatusSyncService` — orchestrates shopPRO→orderPRO status synchronisation
- `ShopproPaymentStatusSyncService` — polls shopPRO `paid` flag and updates `orders.payment_status`
- `IntegrationSecretCipher` — AES-256-CBC encryption with HMAC-SHA256 authentication (`v1:base64(iv+mac+cipher)`)

### Cron (`src/Modules/Cron/`)

| Class | Responsibility |
|---|---|
| `CronRunner` | Dispatches due schedules to `cron_jobs` queue; processes pending jobs up to `$limit`; delegates to typed handlers |
| `CronRepository` | `findDueSchedules()`, `claimNextPendingJob()`, `markJobCompleted()`, `markJobFailed()`, `enqueueJobFromSchedule()`, `getBoolSetting()`, `getIntSetting()` |
| `AllegroTokenRefreshHandler` | `handle()` → refreshes Allegro OAuth token before expiry |
| `AllegroOrdersImportHandler` | `handle()` → calls `AllegroOrdersSyncService::sync()` |
| `AllegroStatusSyncHandler` | `handle()` → calls `AllegroStatusSyncService::sync()` |
| `ShopproOrdersImportHandler` | `handle()` → calls `ShopproOrdersSyncService::syncAll()` |
| `ShopproStatusSyncHandler` | `handle()` → calls `ShopproStatusSyncService::syncAll()` |
| `ShopproPaymentStatusSyncHandler` | `handle()` → calls `ShopproPaymentStatusSyncService::syncAll()` |

Cron is also triggerable via CLI (`bin/cron.php`) and optionally runs on each HTTP request when `cron_run_on_web=1` (throttled with session timer + DB advisory lock `orderpro_web_cron_lock`).

### Shipments (`src/Modules/Shipments/`)

Provider-agnostic shipment layer built around `ShipmentProviderInterface`:

```php
interface ShipmentProviderInterface {
    public function code(): string;
    public function getDeliveryServices(): array;
    public function createShipment(int $orderId, array $formData): array;
    public function checkCreationStatus(int $packageId): array;
    public function downloadLabel(int $packageId, string $storagePath): array;
}
```

| Class | Provider Code | Responsibility |
|---|---|---|
| `AllegroShipmentService` | `allegro_wza` | Allegro WZA carrier integration |
| `ApaczkaShipmentService` | `apaczka` | Apaczka carrier API: wycena, create, label, points fallback for pickup addresses |
| `ShipmentProviderRegistry` | — | Map of `code → ShipmentProviderInterface`; resolved by `ShipmentController` |
| `ShipmentController` | — | `prepare` (form), `create`, `checkStatus`, `label` endpoints |
| `ShipmentPackageRepository` | — | CRUD for `shipment_packages` table |

### Users (`src/Modules/Users/`)

| Class | Responsibility |
|---|---|
| `UsersController` | List users, create user |
| `UserRepository` | Find by email, list, insert/update |

---

## 5. Core Domain Concepts

### Order Aggregate

The order domain is provider-neutral. All external orders (Allegro, shopPRO) are normalised into the same tables:

```
orders                      ← main record (source, integration_id, statuses, totals, flags)
  ├─ order_addresses        ← 1:N  (type: customer | delivery | invoice)
  ├─ order_items            ← 1:N  (products, quantities, media_url)
  ├─ order_payments         ← 1:N  (payment method, amounts)
  ├─ order_shipments        ← 1:N  (tracking numbers, provider info)
  ├─ order_documents        ← 1:N  (invoices, etc.)
  ├─ order_notes            ← 1:N  (internal notes)
  ├─ order_status_history   ← 1:N  (status transitions with timestamps)
  └─ order_activity_log     ← 1:N  (universal event log: status_change, payment, shipment, import, note, ...)
```

Key `orders` columns:
- `source` — origin system (`allegro`, `shoppro`)
- `source_order_id` — external ID in source system
- `integration_id` — FK to `integrations.id`
- `internal_order_number` — `OPXXXXXXXXX` (unique internal identifier, e.g. `OP000000001`)
- `external_status_id` / `external_status_code` — last known status from source
- `payment_status` — payment state (`0`=unpaid, `2`=paid, etc.)
- `ordered_at` / `source_created_at` / `source_updated_at` / `fetched_at` — date fallback chain

### Integration Registry (`integrations` table)

Single base table for all integration instances. Specific settings are in satellite tables linked by `integration_id`:

```
integrations (type, name, is_active, api_key_encrypted, orders_fetch_enabled, ...)
  ├─ allegro_integration_settings  (1:1, environment, OAuth tokens, token_expires_at)
  ├─ apaczka_integration_settings  (1:1, app_id, app_secret_encrypted)
  └─ inpost_integration_settings   (1:1, api_token, organization_id, defaults)

integrations (type=shoppro, multi-instance)
  ├─ order_status_mappings         (1:N, shoppro_status_code → orderpro_status_code)
  └─ shoppro_delivery_method_mappings (1:N, delivery method → carrier service)
```

### Status Configuration

```
order_status_groups    (name, code, color_hex, sort_order, is_active)
  └─ order_statuses    (1:N, name, code, sort_order, is_active)
```

Status codes in `orders` (`external_status_code`) are mapped to human labels via join with `order_statuses`. Fallback group "Pozostale" catches unmapped codes.

External status mappings per provider:
- `allegro_order_status_mappings` — `allegro_status_code → orderpro_status_code`
- `order_status_mappings` — generic per-integration mapping (`shoppro_status_code → orderpro_status_code`)

### Carrier / Delivery Method Mappings

```
carrier_delivery_method_mappings
  source_system + source_integration_id + order_delivery_method
    → provider + provider_service_id + provider_account_id
```

This is the unified resolution table used by `ShipmentController` to auto-select the carrier service when preparing a shipment.

### Cron Scheduling Tables

```
cron_schedules  (job_type, interval_seconds, priority, is_active, next_run_at)
  → cron_jobs   (job_type, payload, status, priority, scheduled_at, result_json, ...)
```

`CronRunner` reads due schedules, enqueues jobs, then claims and processes pending jobs up to the configured limit.

---

## 6. Dependency Injection Pattern

The application does not use a DI container. All dependencies are wired manually in `routes/web.php` (for HTTP) and in `Application::maybeRunCronOnWeb()` (for web cron). This means:

- Every controller receives its dependencies via constructor injection.
- `Application` holds the core singletons (PDO, AuthService, OrdersRepository, etc.) and exposes them via typed getters (`$app->db()`, `$app->orders()`, `$app->auth()`, etc.).
- `routes/web.php` is the composition root for the web context.

---

## 7. Security Architecture

| Concern | Mechanism |
|---|---|
| Authentication | Session-based. `AuthService::check()` reads `$_SESSION`. `AuthMiddleware` guards all protected routes. |
| CSRF | `Csrf::token()` / `Csrf::validate()` — single session token, validated on all POST handlers before any mutation. |
| Secret storage | API keys and OAuth tokens encrypted at-rest using `IntegrationSecretCipher` (AES-256-CBC + HMAC-SHA256). Secret key comes from `INTEGRATIONS_SECRET` env var. |
| XSS | Template helper `$e()` wraps `htmlspecialchars()` with `ENT_QUOTES`. |
| SQL injection | All queries use PDO prepared statements (medoo-style named params). No raw string concatenation. |
| DB locks | `GET_LOCK` used for migrations (`orderpro_migrations_lock`) and web cron (`orderpro_web_cron_lock`) to prevent concurrent execution. |

---

## 8. Database Design Summary

**Migration system:** SQL files in `database/migrations/` named `YYYYMMDD_NNNNNN_description.sql`, sorted alphabetically and tracked in `migrations` table. Applied via `Migrator::runPending()` from UI or CLI (`bin/migrate.php`).

**Core tables:**

| Table | Purpose |
|---|---|
| `users` | Panel users (email, password_hash) |
| `orders` | Master order record |
| `order_addresses` | Typed addresses per order (customer/delivery/invoice) |
| `order_items` | Order line items with media_url |
| `order_payments` | Payment records per order |
| `order_shipments` | Shipment/tracking records from source system |
| `order_documents` | Document references (invoices etc.) |
| `order_notes` | Internal notes |
| `order_status_history` | Full status transition history |
| `order_activity_log` | Universal event log (status_change, payment, shipment, import, note, document, message) |
| `order_status_groups` | Configurable status groups (with color, sort) |
| `order_statuses` | Statuses within groups |
| `order_status_mappings` | External status → orderPRO status per integration (generic) |
| `allegro_order_status_mappings` | Allegro-specific status mappings |
| `integrations` | Base table for all integration instances (allegro, apaczka, inpost, shoppro) |
| `allegro_integration_settings` | Allegro OAuth2 credentials and tokens (1:1 with integrations) |
| `apaczka_integration_settings` | Apaczka app_id + secrets (1:1 with integrations) |
| `inpost_integration_settings` | InPost ShipX config and defaults (1:1 with integrations) |
| `integration_order_sync_state` | Import cursor per integration (last synced order, timestamps) |
| `carrier_delivery_method_mappings` | Unified: order delivery method → shipment provider service |
| `shoppro_delivery_method_mappings` | shopPRO-specific delivery mappings (legacy, superseded by carrier table) |
| `shipment_packages` | Packages created via shipment providers (status, tracking, label path) |
| `company_settings` | Single-row sender company config (address, contact_person, package defaults) |
| `cron_schedules` | Named job schedules with intervals and priorities |
| `cron_jobs` | Job queue: pending, running, completed, failed |
| `app_settings` | Key-value settings store (cron_run_on_web, allegro_status_sync_direction, etc.) |
| `migrations` | Applied migration filenames (Migrator tracking) |

---

## 9. CLI Scripts (`bin/`)

| Script | Purpose |
|---|---|
| `bin/cron.php` | CLI cron runner; loads app and calls `CronRunner::run($limit)` |
| `bin/migrate.php` | CLI migration runner; calls `Migrator::runPending()` |
| `bin/deploy_and_seed_orders.php` | Applies order schema draft + seeds test data (`--count`, `--append`, `--profile=default\|realistic`) |
| `bin/fix_status_codes.php` | Repairs status group/status codes (PL→ASCII transliteration, `--dry-run`) |
| `bin/fill_order_item_images.php` | Backfills `order_items.media_url` from integration APIs |
| `bin/randomize_order_statuses.php` | Dev utility to randomize order statuses |
| `bin/fix_gs1_brand.php` | Fixes GS1 brand data |
| `bin/test_gs1_api.php` | Tests GS1 API connectivity |

---

## 10. Frontend Architecture

- **Styles:** SCSS source in `resources/scss/`, compiled to `public/assets/css/`.
- **Scripts:** JS in `resources/modules/` (e.g. `jquery-alerts`), compiled to `public/assets/js/modules/`.
- **Alerts/confirms:** `window.OrderProAlerts.confirm(...)` from `public/assets/js/modules/jquery-alerts.js`. Native `alert()`/`confirm()` are forbidden.
- **Views:** Plain PHP; no JS framework. Inline JS kept minimal, page-level only in view files.
- **Layout:** Single shell `resources/views/layouts/app.php` with sidebar nav. Sidebar `activeMenu` and `activeSettings` variables control highlighted state.

---

*Full architecture analysis: 2026-03-12*