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

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