# Codebase Structure

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

## Directory Layout

```
bilety.brzezovka.pl/
├── autoload/               # PHP autoloaded classes (MVC layers + core utilities)
│   ├── controls/           # Controllers (request handlers per module)
│   ├── factory/            # Business logic and DB query services
│   ├── view/               # View composers (layout wrapping)
│   ├── class.S.php         # Session, utilities, email
│   ├── class.Tpl.php       # Template engine
│   ├── class.Html.php      # Form component builder
│   ├── class.DbModel.php   # Active-record base class
│   ├── class.Excel.php     # Order Excel export
│   └── class.Cron.php      # Cron stub
├── templates/              # PHP HTML templates
│   ├── tickets/            # Customer-facing ticket shop
│   ├── admin-panel/        # Admin order management
│   ├── site/               # Layout wrappers
│   ├── html/               # Reusable form components
│   ├── components/         # UI fragments (spinner, etc.)
│   └── cron/               # Cron output
├── libraries/              # Vendored PHP dependencies
│   ├── rb.php              # RedBeanPHP ORM
│   ├── phpmailer/          # PHPMailer SMTP
│   └── phpqrcode/          # QR code generator
├── layout/                 # Frontend assets
│   ├── style-scss/         # SCSS source files
│   ├── style-css/          # Compiled CSS
│   └── images/             # Logos, icons
├── orders/                 # Generated QR code PNGs (web-accessible)
├── .paul/                  # PAUL project planning files
├── .vscode/                # VS Code settings + FTP sync config
├── index.php               # Main web entry point
├── ajax.php                # AJAX endpoint
├── api.php                 # API endpoint
├── cron.php                # Scheduled tasks entry point
└── config.php              # All configuration (DB, SMTP, tickets, keys)
```

## Directory Purposes

**`autoload/`:**
- Purpose: All PHP application classes, autoloaded by `spl_autoload_register`
- Naming convention: `class.{ClassName}.php`
- Namespace→path mapping: `\controls\Tickets` → `autoload/controls/class.Tickets.php`

**`autoload/controls/`:**
- Purpose: Controller classes — one per module
- Key files: `class.Tickets.php` (888 lines, ticket shop), `class.Apanel.php`, `class.Users.php`, `class.Scanner.php`, `class.Site.php` (router)

**`autoload/factory/`:**
- Purpose: Business logic and DB query classes
- Key files: `class.Tickets.php` (calendar, basket), `class.Apanel.php` (settings), `class.Users.php` (auth)

**`autoload/view/`:**
- Purpose: Layout composers — wrap controller output in site templates
- Key files: `class.Site.php` (main layout dispatcher)

**`templates/`:**
- Purpose: PHP HTML templates rendered by `\Tpl::view()`
- Subdirs match module names; files use kebab-case: `main-view.php`, `order-data.php`

**`libraries/`:**
- Purpose: Vendored third-party PHP libraries (no Composer)
- Do not modify; update by replacing files

**`layout/`:**
- Purpose: Frontend assets
- SCSS compiled via VS Code Live Sass Compiler — edit `style-scss/`, output goes to `style-css/`

**`orders/`:**
- Purpose: Runtime-generated QR code PNG storage
- Structure: `orders/{hash[0]}/{hash[1]}/{hash}.png`
- Web-accessible (referenced in confirmation emails and scanner)

## Key File Locations

**Entry Points:**
- `index.php` — All web requests
- `ajax.php` — jQuery AJAX calls
- `api.php` — External API access
- `cron.php` — Scheduled background tasks

**Configuration:**
- `config.php` — Everything: DB, SMTP, ticket types/prices, payment keys, admin password

**Core Logic:**
- `autoload/controls/class.Tickets.php` — Full ticket purchase flow + P24 payment
- `autoload/controls/class.Apanel.php` — Admin order management
- `autoload/factory/class.Tickets.php` — Calendar availability, basket logic
- `autoload/class.S.php` — Session, email, utility methods used everywhere

**Templates:**
- `templates/tickets/main-view.php` — Ticket selection + calendar UI
- `templates/tickets/basket-form.php` — Customer details checkout form
- `templates/tickets/przelewy24.php` — Payment gateway form
- `templates/tickets/order-confirm.php` — Post-payment confirmation
- `templates/admin-panel/main-view.php` — Orders list table
- `templates/admin-panel/order-data.php` — Order detail + edit modal
- `templates/site/layout-logged.php` — Main site wrapper

**Styles:**
- `layout/style-scss/style.scss` — SCSS source (compile with Live Sass Compiler)
- `layout/style-css/style.css` — Compiled output (don't edit directly)

## Naming Conventions

**Files:**
- `class.{ClassName}.php` — All PHP class files in `autoload/`
- `kebab-case.php` — Template files in `templates/`
- `style.scss` / `style.css` — Single compiled stylesheet

**Directories:**
- Singular for layers: `controls/`, `factory/`, `view/`
- Module-named for templates: `tickets/`, `admin-panel/`, `site/`
- Lowercase throughout

## Where to Add New Code

**New controller action (e.g., `/tickets/new_action/`):**
- Method: `autoload/controls/class.Tickets.php` — add `static public function new_action()`
- Template: `templates/tickets/new-action.php`
- Business logic: `autoload/factory/class.Tickets.php`

**New admin panel feature:**
- Controller: `autoload/controls/class.Apanel.php`
- Template: `templates/admin-panel/`
- Logic: `autoload/factory/class.Apanel.php`

**New module (e.g., `/reports/`):**
- Controller: `autoload/controls/class.Reports.php`
- Factory: `autoload/factory/class.Reports.php`
- View: `autoload/view/class.Reports.php` (if custom layout needed)
- Templates: `templates/reports/`

**New utility method:**
- Add to `autoload/class.S.php` as static method

**SCSS changes:**
- Edit `layout/style-scss/style.scss` — save triggers Live Sass Compiler

## Special Directories

**`orders/`:**
- Generated at runtime; not in git (should be gitignored)
- Contains QR code PNGs served directly by web server

**`.paul/`:**
- PAUL project planning files
- Committed to git as project documentation

---

*Structure analysis: 2026-04-26*
*Update when directory structure changes*