# 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)

```text
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`