docs: map existing codebase

- stack.md - Technologies and dependencies - architecture.md - System design and patterns - structure.md - Directory layout - conventions.md - Code style and patterns - testing.md - Test structure (none) - integrations.md - External services - concerns.md - Technical debt and issues - db_schema.md - Database schema and relationships Co-Authored-By: Claude <noreply@anthropic.com>
2026-04-26 22:15:02 +02:00
parent b6697352e9
commit 5bbec72b59
9 changed files with 989 additions and 0 deletions
--- a/.paul/codebase/structure.md
+++ b/.paul/codebase/structure.md
@@ -0,0 +1,159 @@
+# 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*