docs: map existing codebase

- stack.md (68 lines) - PHP/MySQL/Apache stack, vendored libraries - architecture.md (131 lines) - Custom MVC CMS, dual-layer (front/admin) - structure.md (170 lines) - Directory layout and conventions - conventions.md (98 lines) - PHP snake_case, SCSS $c/$f prefixes, jQuery patterns - testing.md (49 lines) - No automated tests detected - integrations.md (111 lines) - Google Maps, PHPMailer, Pixieset, Facebook - concerns.md (150 lines) - Critical security issues: hardcoded creds, MD5, unserialize - db_schema.md (260 lines) - ~32 tables with pp_ prefix, inferred from source - tech_changelog.md (9 lines) - Initial log entry Co-Authored-By: Claude <noreply@anthropic.com>
2026-05-05 22:02:04 +02:00
parent 2d3bb66d42
commit cf1a0adb0b
10 changed files with 1377 additions and 0 deletions
--- a/.paul/codebase/structure.md
+++ b/.paul/codebase/structure.md
@@ -0,0 +1,203 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-05-05
+
+## Directory Layout
+
+```
+vidok.com/
+├── index.php               # Frontend entry point
+├── ajax.php                # Frontend AJAX handler
+├── config.php              # Database credentials (hardcoded)
+├── download.php            # Secure file download handler
+├── get_file.php            # PDF/document download wrapper
+├── api/                    # JSON API endpoints
+├── admin/                  # Admin panel application
+│   ├── index.php           # Admin entry point
+│   ├── ajax.php            # Admin AJAX handler
+│   ├── css/                # Admin SCSS source files
+│   ├── style-css/          # Compiled admin CSS
+│   └── templates/          # Admin UI PHP templates
+├── autoload/               # Core PHP classes (MVC layers)
+│   ├── class.S.php         # Global static helpers
+│   ├── class.Tpl.php       # Template engine
+│   ├── class.Cache.php     # Session cache
+│   ├── class.Html.php      # HTML generation helpers
+│   ├── class.Image.php     # Image processing
+│   ├── front/              # Frontend MVC classes
+│   │   ├── controls/       # Frontend controllers
+│   │   ├── factory/        # Frontend models (DB queries)
+│   │   └── view/           # Frontend HTML generators
+│   └── admin/              # Admin MVC classes
+│       ├── controls/       # Admin controllers
+│       ├── factory/        # Admin models (DB queries)
+│       └── view/           # Admin HTML generators
+├── templates/              # Default frontend PHP templates
+│   ├── articles/           # Article display templates
+│   ├── pages/              # Page display templates
+│   ├── site/               # Layout partials (header, footer, etc.)
+│   ├── newsletter/         # Newsletter form templates
+│   └── widgets/            # Widget templates
+├── templates_user/         # Custom frontend templates (override defaults)
+├── layout/                 # Frontend CSS, JS, fonts
+│   ├── style-scss/         # SCSS source files
+│   │   ├── _variables.scss # Color/font variables
+│   │   ├── _mixins.scss    # Responsive breakpoints, mixins
+│   │   └── style.scss      # Main SCSS entry point
+│   ├── style-css/          # Compiled frontend CSS
+│   └── js/                 # Frontend JavaScript
+│       ├── main.js         # Main frontend JS
+│       └── custom.js       # Custom frontend JS
+├── libraries/              # Vendored PHP/JS libraries
+│   ├── medoo/              # Medoo ORM
+│   ├── phpmailer/          # PHPMailer for email
+│   ├── ckeditor/           # Rich text editor
+│   ├── grid/               # Admin data grid component
+│   ├── bootstrap-4.1.3/    # Bootstrap 4
+│   ├── bootstrap-5.0/      # Bootstrap 5
+│   ├── font-awesome-6.1.1/ # Icon library
+│   ├── swiper/             # Carousel library
+│   ├── framework/          # Date pickers, moment.js
+│   └── jquery/             # jQuery utilities (lozad, captcha)
+├── plugins/                # Hook files for extensibility
+│   ├── special-actions.php          # Early hooks
+│   ├── special-actions-middle.php   # Contact forms, file uploads
+│   └── special-actions-end.php      # Late hooks
+├── images/                 # User-uploaded images
+├── upload/                 # User-uploaded files
+├── cache/                  # Runtime cache + generated WebP images
+├── stopki/                 # Footer content fragments
+├── .paul/                  # PAUL project management files
+├── .vscode/                # VS Code settings (SCSS compile, SFTP)
+└── .htaccess               # Apache URL rewriting rules
+```
+
+## Directory Purposes
+
+**`autoload/`:**
+- Purpose: All PHP application classes — the core of the CMS
+- Pattern: `class.ClassName.php` naming
+- Namespaced: `front\controls\`, `front\factory\`, `front\view\`, `admin\controls\`, `admin\factory\`, `admin\view\`
+- Key files: `class.S.php` (global helpers), `class.Tpl.php` (templating), `class.Image.php`
+
+**`admin/templates/`:**
+- Purpose: PHP template files for admin panel UI
+- Organized by module: `articles/`, `pages/`, `users/`, `newsletter/`, `layouts/`, `scontainers/`, `html/`
+- Key files: `articles/article-edit.php`, `pages/page-edit.php`, `site/main-layout.php`
+
+**`templates/` and `templates_user/`:**
+- Purpose: Frontend page templates
+- `templates/` — default templates (shipped with CMS)
+- `templates_user/` — project-specific overrides (take precedence over defaults)
+- `Tpl::view()` checks `templates_user/` first, falls back to `templates/`
+
+**`layout/`:**
+- Purpose: All frontend CSS, JS, fonts
+- SCSS source in `layout/style-scss/`, compiled output in `layout/style-css/`
+- JS in `layout/js/`
+
+**`libraries/`:**
+- Purpose: All vendored third-party libraries (no package manager)
+- PHP libraries: Medoo, PHPMailer, Grid
+- JS libraries: CKEditor, Bootstrap, Swiper, DatePickers
+
+**`plugins/`:**
+- Purpose: Extension hooks called from `index.php` at different lifecycle stages
+- `special-actions-middle.php` is the main plugin — contains all contact form handlers and reCAPTCHA
+
+**`cache/`:**
+- Purpose: Runtime-generated files (WebP images)
+- Auto-created by `\Image` class during first request
+- Not committed to git (runtime data)
+
+## Key File Locations
+
+**Entry Points:**
+- `index.php` — public frontend entry
+- `ajax.php` — frontend AJAX
+- `admin/index.php` — admin panel entry
+- `admin/ajax.php` — admin AJAX
+- `api/contact_map.php` — contacts/locations JSON API
+
+**Configuration:**
+- `config.php` — database credentials (single config file, no .env)
+- `admin/ip.conf` — optional IP whitelist for admin panel
+- `.vscode/settings.json` — SCSS compile settings
+
+**Core Logic:**
+- `autoload/class.S.php` — global helpers (images, cache, email, sessions)
+- `autoload/class.Tpl.php` — template engine
+- `autoload/front/view/class.Site.php` — main frontend page renderer
+- `autoload/admin/view/class.Page.php` — main admin page renderer
+- `libraries/medoo/medoo.php` — database ORM
+
+**Templates (Frontend):**
+- `templates/articles/` — article display patterns
+- `templates/site/` — header, footer, contact, Facebook widget
+- `templates_user/page-contact-v*.php` — custom contact page variants
+
+## Naming Conventions
+
+**PHP Class Files:**
+- Pattern: `class.ClassName.php` (e.g., `class.Articles.php`, `class.Users.php`)
+- Namespace mirrors directory: `admin\factory\` = `autoload/admin/factory/class.*.php`
+
+**PHP Templates:**
+- Pattern: `feature-type.php` in kebab-case (e.g., `article-edit.php`, `articles-browse-list.php`)
+
+**SCSS/CSS:**
+- Helper files: `_variables.scss`, `_mixins.scss` (underscore prefix)
+- Feature files: kebab-case (e.g., `drzwi-wejsciowe-aluminiowe.scss`)
+- Compiled output in `style-css/` mirroring `style-scss/`
+
+**Directories:**
+- Feature groupings in kebab-case
+- Plural for collections: `articles/`, `templates/`, `controls/`
+
+## Where to Add New Code
+
+**New Content Module (e.g., "Events"):**
+- Admin factory: `autoload/admin/factory/class.Events.php`
+- Admin controls: `autoload/admin/controls/class.Events.php`
+- Admin view: `autoload/admin/view/class.Events.php`
+- Admin templates: `admin/templates/events/`
+- Frontend factory: `autoload/front/factory/class.Events.php`
+- Frontend templates: `templates_user/events/` or `templates/events/`
+
+**New Frontend Page Template:**
+- Custom: `templates_user/page-[name].php`
+- Default: `templates/pages/page-[type].php`
+
+**New Contact Form Variant:**
+- Add handler to `plugins/special-actions-middle.php`
+
+**New AJAX Action:**
+- Frontend: add `case` in `ajax.php`
+- Admin: add `case` in `admin/ajax.php`
+
+**New JS/CSS:**
+- Frontend JS: `layout/js/custom.js` or new file in `layout/js/`
+- Frontend SCSS: `layout/style-scss/` (compiled by Live Sass Compiler)
+- Admin SCSS: `admin/css/custom.scss`
+
+## Special Directories
+
+**`cache/`:**
+- Purpose: Runtime-generated WebP images and temporary cache
+- Source: Auto-generated by `\Image` class and `\Cache` class
+- Committed: No (runtime data, not in git)
+
+**`admin/temp/`:**
+- Purpose: Temporary file uploads during admin operations
+- Source: File upload handlers
+- Committed: Should not be committed
+
+**`templates_user/`:**
+- Purpose: Project-specific template overrides
+- Source: Manual creation — customizations live here
+- Committed: Yes (project-specific content)
+
+---
+
+*Structure analysis: 2026-05-05*
+*Update when directory structure changes*