# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Online ticket sales system for **Kompleks Turystyczny Brzezovka** (amusement park in Kolbuszowa, Poland). Handles ticket purchase, shopping cart, Przelewy24 payments, QR code generation, invoice issuing (via fakturowo.pl API), and a QR ticket scanner for staff.

Live at: `bilety.brzezovka.pl`

## Architecture

Custom PHP MVC without a framework. No Composer — all dependencies are vendored in `libraries/`.

### Request Flow

1. `.htaccess` rewrites URLs as `/{module}/{action}/{params}` → `index.php?module=X&action=Y&...`
2. `index.php` bootstraps: autoloader, config, DB connections (Medoo + RedBeanPHP), session
3. `\view\Site::show()` → `\controls\Site::route()` resolves `module`/`action` to a controller method via `\controls\{Module}::{action}()`
4. Controllers return rendered HTML via `\Tpl::view('template-name', $vars)`

### Autoloader Convention

`spl_autoload_register` maps namespaced classes to files:
- `\controls\Tickets` → `autoload/controls/class.Tickets.php`
- `\factory\Tickets` → `autoload/factory/class.Tickets.php`
- `\view\Site` → `autoload/view/class.Site.php`
- `\S`, `\Tpl`, `\DbModel`, `\Html` → `autoload/class.{Name}.php`

### Layer Responsibilities

| Layer | Namespace/Dir | Role |
|-------|--------------|------|
| Controllers | `autoload/controls/` | Handle actions, coordinate logic, return rendered views |
| Factory (Services) | `autoload/factory/` | Business logic, DB queries, data processing |
| Views | `autoload/view/` | Layout assembly (wraps controller output in site layout) |
| Templates | `templates/` | PHP template files rendered by `Tpl::view()` |
| Core classes | `autoload/` (root) | `S` (utility/session), `Tpl` (templating), `DbModel` (active record), `Html` (form helpers) |

### Key Modules

| Module | Controller | Purpose |
|--------|-----------|---------|
| `tickets` | `controls\Tickets` | Public ticket shop: browse, add/remove from cart, checkout, payment |
| `apanel` | `controls\Apanel` | Admin panel: order list, order editing, ticket validation |
| `scanner` | `controls\Scanner` | QR code scanner for on-site ticket verification |
| `users` | `controls\Users` | User login/logout, settings, permissions |

### Database

MySQL via two ORMs used in parallel:
- **Medoo** (`$mdb` global) — primary query builder for tickets/orders
- **RedBeanPHP** (`\R::`) — used in cron jobs (CEIDG import)

Main tables: `orders`, `order_tickets`, `users`

### Entry Points

| File | Purpose |
|------|---------|
| `index.php` | Main app entry (web requests) |
| `ajax.php` | AJAX endpoint (same autoloader, Medoo only) |
| `api.php` | API endpoint (autoloader + Medoo + PHPMailer + RedBeanPHP) |
| `cron.php` | Scheduled tasks (email reminders, CEIDG import) |

### External Integrations

- **Przelewy24** — payment gateway (merchant config in `config.php`)
- **fakturowo.pl** — invoice/receipt generation via API
- **PHPMailer** — email sending (SMTP via `bilety@brzezovka.pl`)
- **phpqrcode** — QR code generation for order hashes

## Frontend

- Bootstrap 5.2, jQuery 3.6, Font Awesome 6.1
- SCSS in `layout/style-scss/` compiled to `layout/style-css/style.css`
- SCSS compile comment: `// out: ../style-css/style.css, compress: true, sourceMap: true` (Live Sass Compiler)
- DataTables for admin order list
- html5-qrcode for scanner
- Datepicker for ticket date selection

## Key Conventions

- All controller methods are `static public` and accessed via URL routing
- Global `$settings`, `$mdb`, `$user` are used throughout (no DI)
- Ticket config (prices, types, dynamic pricing) lives entirely in `config.php`
- Session-based shopping cart stored at `$_SESSION['basket']`
- Admin auth is a single shared password (`$settings['admin-password']`), stored in session as `$_SESSION['user']`
- Template rendering: `\Tpl::view('path/template-name', ['key' => $value])` — variables accessible as `$this->key` in templates
- AJAX responses: controllers `echo json_encode(...)` then `exit;`

## Development

- No build system, test framework, or package manager
- SCSS compilation: use VS Code "Live Sass Compiler" extension (configured via first-line comment in `style.scss`)
- Deployment: FTP sync (`.vscode/ftp-kr.sync.cache.json` present)
- PHP version: compatible with PHP 7.4+ (no typed properties, uses legacy autoload pattern)
- Timezone: `Europe/Warsaw`
- Language: Polish (all UI text, comments, variable names mix PL/EN)