bilety.brzezovka.pl/.paul/codebase/architecture.md

# Architecture

**Analysis Date:** 2026-04-26

## Pattern Overview

**Overall:** Custom PHP MVC (no framework)

**Key Characteristics:**
- URL-based routing via Apache mod_rewrite in `.htaccess`
- Namespace-organized layers (controls, factory, view)
- Custom autoloader mapping namespaces to file paths
- Session-based shopping cart (no cart persistence until order submit)
- Static public methods as controller actions
- Single config file (`config.php`) containing all settings and ticket definitions

## Layers

**Controller Layer (`autoload/controls/`):**
- Purpose: Handle HTTP actions, coordinate factory/template calls, return rendered HTML
- Contains: Route action methods (e.g., `main_view()`, `basket_view()`, `przelewy24_response()`)
- Depends on: Factory layer, `\Tpl`, `\S`, `\Html`, `global $settings, $mdb, $user`
- Used by: `\controls\Site::route()` dispatcher

**Factory/Service Layer (`autoload/factory/`):**
- Purpose: Business logic, database queries, data processing
- Contains: Calendar availability, order creation, user auth, settings management
- Depends on: `global $mdb` (Medoo), `\R::` (RedBeanPHP)
- Used by: Controllers

**View Layer (`autoload/view/`):**
- Purpose: Layout assembly — wraps controller output in site layout template
- Contains: `show()` dispatcher, layout selection logic
- Depends on: Controllers (via `\controls\Site::route()`), `\Tpl`
- Used by: Entry points (`index.php` calls `\view\Site::show()`)

**Template Layer (`templates/`):**
- Purpose: HTML rendering with embedded PHP
- Contains: Module-organized `.php` template files
- Variables accessed via `$this->key` (injected by `\Tpl`)
- Used by: Any layer via `\Tpl::view('path/name', ['key' => $value])`

**Core Utilities (`autoload/`):**
- `\S` — Session management, email, utilities (`autoload/class.S.php`)
- `\Tpl` — Template engine with variable injection (`autoload/class.Tpl.php`)
- `\Html` — Form component builder (`autoload/class.Html.php`)
- `\DbModel` — Simple active-record base class (`autoload/class.DbModel.php`)

## Data Flow

**HTTP Request Lifecycle:**

1. Browser requests `/tickets/basket_view/`
2. `.htaccess` rewrites to `index.php?module=tickets&action=basket_view`
3. `index.php` bootstraps: autoloader, config, Medoo, RedBeanPHP, PHPMailer, session security
4. `\view\Site::show()` called
5. `\controls\Site::route()` resolves module + action to `\controls\Tickets::basket_view()`
6. Controller method executes: reads session basket, calls factory methods, calls `\Tpl::view()`
7. Rendered HTML returned as string to `\view\Site::show()`
8. `show()` wraps content in `templates/site/layout-logged.php`
9. Final HTML output sent to browser

**AJAX Request Lifecycle:**

1. JavaScript POSTs to `ajax.php?module=tickets&action=ticket_add`
2. `ajax.php` bootstraps similarly to `index.php`
3. Controller method executes, modifies `$_SESSION['basket']`
4. `echo json_encode([...]); exit;` returns JSON response

**Ticket Purchase Flow:**

1. `main_view()` — Shows available tickets + calendar
2. `ticket_add()` — AJAX: validates date, calculates price, updates `$_SESSION['basket']`
3. `basket_view()` — Shows cart + customer form
4. `basketFormHandler()` — Inserts `orders` + `order_tickets` records, generates QR code PNG
5. `przelewy24()` — Renders payment form for P24 gateway
6. `przelewy24_response()` — P24 webhook: marks order paid, generates invoice, sends email
7. `order_confirm()` — Shows final confirmation + Google Analytics data layer

**State Management:**
- Shopping cart: `$_SESSION['basket']` (array keyed by ticket product_id)
- Admin auth: `$_SESSION['user']` (boolean for admin, array for staff users)
- Flash messages: `$_SESSION['alert']` (cleared after display)
- Session regenerated on first visit; IP-validated on each request

## Key Abstractions

**Module/Controller:**
- Purpose: Group of static methods handling a URL namespace (e.g., `/tickets/`)
- Examples: `autoload/controls/class.Tickets.php`, `autoload/controls/class.Apanel.php`
- Pattern: Static public methods, one per URL action

**Factory:**
- Purpose: Data access and business logic for a domain
- Examples: `autoload/factory/class.Tickets.php`, `autoload/factory/class.Users.php`
- Pattern: Static methods returning data arrays or modifying DB

**`\S` Utility Class:**
- Purpose: Centralized session, request, and utility operations
- Key methods: `S::get()` (unified POST/GET), `S::get_session()`, `S::set_session()`, `S::send_email()`, `S::hash()`, `S::alert()`
- Accessed statically throughout the codebase

**`\Tpl` Template Engine:**
- Purpose: Render PHP templates with variable injection
- Usage: `\Tpl::view('tickets/main-view', ['tickets' => $arr])`
- Variables accessible in template as `$this->tickets`
- Template lookup order: `templates_user/` → `templates/` → root

## Entry Points

**`index.php`:**
- Triggers: All web page requests
- Responsibilities: Session bootstrap, DB init, autoloader, calls `\view\Site::show()`

**`ajax.php`:**
- Triggers: jQuery AJAX calls from frontend
- Responsibilities: Same bootstrap as index.php, routes to controller AJAX actions

**`api.php`:**
- Triggers: External API calls (mobile or third-party)
- Responsibilities: API-specific bootstrap

**`cron.php`:**
- Triggers: Server cron job (scheduled tasks)
- Responsibilities: Email reminders, CEIDG import, task chaining

## Error Handling

**Strategy:** Minimal — most errors are silent (error_reporting suppresses notices/warnings)

**Patterns:**
- Factories return empty arrays on failure (no exceptions thrown)
- No try/catch in most controller methods
- cURL errors ignored (return value unchecked in payment flow)
- `error_reporting(E_ALL ^ E_NOTICE ^ E_STRICT ^ E_WARNING ^ E_DEPRECATED)` in entry points

## Cross-Cutting Concerns

**Session Security:**
- IP address validated on every request; session destroyed if changed
- Session regenerated once on first visit
- Implementation: `index.php` lines 27-31

**Globals:**
- `$settings` — all configuration (from `config.php`)
- `$mdb` — Medoo DB connection
- `$user` — current user (from session)
- Accessed via `global $settings, $mdb, $user` at top of controller methods

**Template Variables:**
- All templates receive data via `\Tpl::view()` second argument
- No direct template output buffering or inheritance

---

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