shopPRO/.paul/docs/ARCHITECTURE.md

ARCHITECTURE

Scope

Dokument opisuje aktualna architekture runtime projektu shopPRO:

• warstwy aplikacji i ich odpowiedzialnosci,
• przeplywy requestow (admin/front/api),
• Dependency Injection i miejsca wiringu,
• konwencje autoloadera i namespace,
• granice miedzy nowa architektura a pozostalosciami legacy.

High-level layout

Kod aplikacji jest podzielony na 4 glowne warstwy:

1. autoload/Domain/ - logika biznesowa i dostep do danych (28 modulow)
2. autoload/admin/ - panel administracyjny (router + kontrolery + form system)
3. autoload/front/ - frontend sklepu (router + layout engine + kontrolery/widoki)
4. autoload/api/ - REST API (api.php, ApiRouter, kontrolery endpointow)

Komponenty wspoldzielone sa trzymane w autoload/Shared/.

Directory map (runtime)

autoload/
  Domain/                 # 28 modulow domenowych
  Shared/                 # Cache, Helpers, Tpl, Html, Email, Image
  admin/
    App.php               # routing + DI factories
    Controllers/          # 28 kontrolerow admin
    Support/              # formularze/tabele
    Validation/           # walidacja formularzy
    ViewModels/           # modele widokow
  front/
    App.php               # routing + DI factories + fallback legacy
    LayoutEngine.php      # silnik layoutu frontend
    Controllers/          # 8 kontrolerow frontend
    Views/                # 11 statycznych klas widokow
  api/
    ApiRouter.php         # auth + endpoint dispatch
    Controllers/          # 4 kontrolery API

Entry points i przeplyw

Admin (admin/index.php)

1. Bootstrap (sesja, DB, autoload)
2. admin\App::update() - uruchamia pending migracje
3. admin\App::special_actions() - logowanie/wylogowanie/2FA
4. admin\App::render():
   • auth gate (lub formularz logowania),
   • route() -> kontroler + akcja,
   • render przez Shared\Tpl\Tpl.

Front (index.php)

1. Bootstrap (sesja, DB, autoload, jezyk)
2. Mapowanie URL (redirecty + routes)
3. front\App::checkUrlParams()
4. front\App::route():
   • artykul/produkt/kategoria,
   • nowe kontrolery DI,
   • fallback do front\controls\* (legacy, jesli istnieje)
5. front\LayoutEngine::show() sklada finalny HTML.

API (api.php)

1. Bootstrap (bez sesji biznesowej)
2. Tworzenie \api\ApiRouter
3. ApiRouter::handle():
   • auth przez X-Api-Key,
   • walidacja endpoint i action,
   • dispatch do kontrolera API,
   • JSON response przez sendSuccess() / sendError().

Szczegolowa specyfikacja endpointow: .paul/docs/API.md.

Dependency Injection (manual factories)

DI jest realizowane recznie w mapach factory:

• admin: autoload/admin/App.php -> getControllerFactories()
• front: autoload/front/App.php -> getControllerFactories()
• api: autoload/api/ApiRouter.php -> getControllerFactories()

Wzorzec:

• router tworzy repozytoria domenowe,
• repozytoria sa wstrzykiwane do kontrolerow przez konstruktor,
• kontroler wywoluje metody domenowe i zwraca HTML/JSON.

Autoloader i namespace rules

Kazdy entry point korzysta z custom autoloadera:

1. autoload/{namespace}/class.{ClassName}.php (legacy)
2. autoload/{namespace}/{ClassName}.php (nowy format)

Mapowanie namespace -> katalog (case-sensitive na Linux):

• \Domain\ -> autoload/Domain/
• \Shared\ -> autoload/Shared/
• \admin\ -> autoload/admin/ (male a)
• \front\ -> autoload/front/
• \api\ -> autoload/api/

Nie uzywac \Admin\ (duze A), bo katalog runtime to admin/.

Domain layer (28 modulow)

Aktualne moduly:

Article, Attribute, Banner, Basket, Cache, Category, Client, Coupon, CronJob, Dashboard, Dictionaries, Integrations, Languages, Layouts, Newsletter, Order, Pages, PaymentMethod, Producer, Product, ProductSet, Promotion, Scontainers, Settings, ShopStatus, Transport, Update, User.

Zasada: logika biznesowa i dostep do danych sa w Domain, bez duplikowania osobnych warstw "admin service" i "front service" dla tych samych przypadkow (wyjatki tylko tam, gdzie historycznie juz istnieja, np. OrderAdminService).

Admin architecture

• Router: admin\App
• Kontrolery: autoload/admin/Controllers/*.php (28 klas)
• Form system:
  • admin\ViewModels\Forms\*
  • admin\Support\Forms\FormRequestHandler
  • admin\Support\Forms\FormFieldRenderer
  • admin\Validation\FormValidator
  • template: admin/templates/components/form-edit.php

Admin ma pelne DI i nie korzysta z fallbacku na legacy kontrolery.

Front architecture

• Router: front\App
• Layout engine: front\LayoutEngine
• Kontrolery DI: autoload/front/Controllers/*.php (8 klas)
• Widoki statyczne: autoload/front/Views/*.php (11 klas)

Wazne: frontend nadal ma fallback do \front\controls\*, wiec architektura jest hybrydowa (new DI + remaining legacy paths).

API architecture

• Router: api\ApiRouter
• Endpointy: orders, products, dictionaries, categories
• Kontrolery: autoload/api/Controllers/*ApiController.php (4 klasy)
• API jest stateless, autoryzowane naglowkiem X-Api-Key

Source-of-truth API to runtime:

• api.php
• autoload/api/ApiRouter.php
• autoload/api/Controllers/*

Shared components

Najwazniejsze klasy wspoldzielone:

• Shared\Cache\CacheHandler, Shared\Cache\RedisConnection
• Shared\Helpers\Helpers
• Shared\Tpl\Tpl
• Shared\Html\Html
• Shared\Email\Email
• Shared\Image\ImageManipulator

Data and cache conventions

• ORM: Medoo ($mdb)
• Prefix tabel: pp_
• Cache: Redis, domyslnie TTL 86400
• Dane cache czesto serializowane (serialize/unserialize)
• Czyszczenie cache produktu: pattern shop\\product:{id}:*

Security boundaries

• Admin:
  • sesja uzytkownika admina,
  • CSRF token w akcjach POST,
  • 2FA email flow (pending session + verify).
• API:
  • X-Api-Key porownywany przez hash_equals(),
  • brak logiki sesyjnej.
• Front:
  • sesja klienta + walidacja przeplywow frontendowych.

Source files

Najwazniejsze pliki do szybkiej orientacji:

• autoload/admin/App.php
• autoload/front/App.php
• autoload/front/LayoutEngine.php
• autoload/api/ApiRouter.php
• .paul/docs/API.md
• docs/PROJECT_STRUCTURE.md