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>

.paul/codebase/integrations.md

@@ -0,0 +1,112 @@
+# External Integrations
+
+**Analysis Date:** 2026-04-26
+
+## APIs & External Services
+
+**Payment Processing:**
+- Przelewy24 — Polish payment gateway for ticket purchases
+  - SDK/Client: Custom cURL integration in `autoload/controls/class.Tickets.php`
+  - Auth: Merchant ID `227658` + CRC key (MD5-signed) in `config.php`
+  - Endpoints: `https://secure.przelewy24.pl/trnVerify` (production), sandbox configurable
+  - Flow: Pre-payment form → P24 hosted page → `przelewy24_response()` webhook callback
+  - Sandbox mode: toggle in `config.php`
+
+**Invoice/Receipt Generation:**
+- fakturowo.pl — Polish invoicing API (paragon or faktura VAT)
+  - SDK/Client: Custom cURL POST in `autoload/controls/class.Tickets.php`
+  - Auth: API ID in `config.php` (`$settings['fakturowo_api_id']`)
+  - Endpoint: `https://konto.fakturowo.pl/api`
+  - Triggered after successful Przelewy24 payment
+  - Returns invoice URL stored in `orders.invoice_url`
+
+## Data Storage
+
+**Databases:**
+- MySQL — Primary data store
+  - Connection: Credentials in `config.php`, instantiated in `index.php:44`
+  - Client: Medoo query builder (`libraries/medoo/medoo.php`)
+  - Secondary ORM: RedBeanPHP (`libraries/rb.php`) used in cron tasks
+
+**File Storage:**
+- Local filesystem — QR code PNG files stored in `orders/{hash[0]}/{hash[1]}/{hash}.png`
+  - Web-accessible directory, predictable path structure
+  - Created with `mkdir($dir, 0755, true)` and `\QRcode::png()`
+
+## Authentication & Identity
+
+**Admin Auth:**
+- Single shared password stored in `config.php` (`$settings['admin-password']`)
+- Session-based: password checked once, `$_SESSION['user'] = true` set
+- No individual admin accounts for ticket operations (single login)
+
+**Staff/User Auth:**
+- Separate user table for named staff (`users` table — id, email, MD5 password)
+- Used for non-ticket modules (projects, finances, etc.)
+- Hard-coded ACL in `autoload/controls/class.Users.php` (`permissions()` method)
+- Login via `autoload/factory/class.Users.php::login()` with MD5 comparison
+
+## Email
+
+**PHPMailer + SMTP:**
+- Library: `libraries/phpmailer/class.phpmailer.php`
+- SMTP host: `h53.seohost.pl` port 25
+- From address: `bilety@brzezovka.pl`
+- Credentials: in `config.php`
+- Fallback: native PHP `mail()` if SMTP unavailable
+- Debug logging: optional to `mail_debug.log`
+- Used for: order confirmations (pre-payment), payment confirmations (with QR PNG attachment)
+- Implementation: `autoload/class.S.php::send_email()`
+
+## Monitoring & Observability
+
+**Error Tracking:** Not detected — no Sentry, Rollbar, or similar
+
+**Analytics:**
+- Google Analytics ecommerce data layer — purchase tracking
+  - `buildPurchaseDataLayer()` in `autoload/controls/class.Tickets.php`
+  - Generates `$purchase_data_layer` passed to `templates/tickets/order-confirm.php`
+  - Fires on order confirmation page
+
+**Logs:**
+- Optional mail debug log: `mail_debug.log` (file-based, in project root)
+- No centralized application logging
+
+## CI/CD & Deployment
+
+**Hosting:** Shared hosting (seohost.pl, Apache)
+
+**Deployment:**
+- FTP sync via VS Code ftp-kr extension
+- Config: `.vscode/ftp-kr.json`, cache: `.vscode/ftp-kr.sync.cache.json`
+- Manual deploy — upload changed files via FTP
+
+**CI Pipeline:** None detected
+
+## Environment Configuration
+
+**Development:**
+- All config in `config.php` (single file, committed to git)
+- No separate dev/staging/prod config files
+- Test mode: `$settings['test_price_mode_secret']` for pricing tests
+
+**Production:**
+- Przelewy24 sandbox toggle: `$settings['p24_sandbox'] = false`
+- All secrets in `config.php` — not managed via environment variables
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- Przelewy24 — `/tickets/przelewy24_response/`
+  - Handled in `autoload/controls/class.Tickets.php::przelewy24_response()`
+  - Verification: MD5 CRC check against P24 parameters
+  - On success: marks order paid, generates invoice, sends confirmation email
+
+**Outgoing:**
+- fakturowo.pl — POST request on payment confirmation
+- Przelewy24 verification — GET/POST to `trnVerify` endpoint to confirm transaction
+
+---
+
+*Integration audit: 2026-04-26*
+*Update when adding/removing external services*