docs: add .paul/codebase/ codebase map (7 documents)

Stack, architecture, conventions, testing, integrations, db_schema, concerns. Generated by PAUL /map-codebase workflow from codebase analysis. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-28 21:40:11 +02:00
parent a95acc355b
commit 78d5743c12
7 changed files with 758 additions and 0 deletions
--- a/.paul/codebase/architecture.md
+++ b/.paul/codebase/architecture.md
@@ -0,0 +1,142 @@
+# Architecture — krolewskie-miody.pl
+
+## Repository Structure
+
+Only `wp-content/` and WordPress root files are tracked in Git.
+`wp-includes/` and `wp-admin/` core directories are present but represent standard WordPress core.
+
+```
+krolewskie-miody.pl/
+├── wp-config.php                  # DB config + constants
+├── .htaccess                      # Rewrites, max_input_vars=10000
+├── index.php                      # WP entry point
+├── wp-blog-header.php             # WP bootstrap
+├── wp-content/
+│   ├── themes/
+│   │   ├── betheme/               # Active theme (parent, no child)
+│   │   ├── twentytwentyfive/
+│   │   ├── twentytwentyfour/
+│   │   └── twentytwentythree/
+│   └── plugins/                   # 76 plugins
+├── .paul/                         # PAUL project management
+├── .serena/                       # Serena AI tooling
+├── .vscode/                       # VS Code + FTP config
+└── CLAUDE.md                      # AI assistant instructions
+```
+
+## Theme Architecture: BeTheme (betheme/)
+
+```
+betheme/
+├── functions.php                  # Theme bootstrap (defines MFN_THEME_VERSION)
+├── style.css                      # Theme header metadata only
+├── woocommerce.php                # WooCommerce template root
+├── header.php / header-shop.php   # Header templates
+├── footer.php                     # Footer template (19KB)
+├── style.php / style-colors.php   # Dynamic PHP-generated CSS
+├── functions/                     # Core theme PHP logic
+│   ├── theme-functions.php        # 119KB — main hooks & functions
+│   ├── theme-head.php             # 79KB — HEAD/frontend logic
+│   ├── theme-woocommerce.php      # 72KB — WooCommerce customization (1,752 lines)
+│   ├── theme-shortcodes.php       # 405KB / 13,793 lines — visual builder shortcodes
+│   ├── theme-hooks.php            # Hook definitions
+│   ├── theme-menu.php             # Menu handling (350 lines)
+│   ├── admin/                     # Admin-side classes
+│   ├── builder/                   # Visual builder (class-mfn-builder*.php)
+│   ├── modules/                   # Dynamic data module
+│   ├── plugins/
+│   │   ├── visual-composer.php    # 81KB VC integration
+│   │   └── elementor/             # Elementor support
+│   ├── post-types/                # Custom post type classes
+│   └── widgets/                   # Theme widgets
+├── woocommerce/                   # 27 WooCommerce template overrides
+│   ├── archive-product.php
+│   ├── content-product.php
+│   ├── content-single-product.php
+│   ├── cart/ (5 files)
+│   ├── checkout/form-checkout.php
+│   ├── single-product/ (6+ files)
+│   ├── loop/ (4 files)
+│   ├── myaccount/downloads.php
+│   └── notices/ (2 files)
+├── muffin-options/
+│   └── theme-options.php          # 337KB master options panel
+├── visual-builder/                # Muffin's visual page builder
+├── css/                           # Pre-compiled stylesheets
+├── js/                            # Pre-compiled JavaScript
+├── includes/                      # Template partials
+├── templates/                     # Page templates
+├── languages/                     # Translations
+└── wpml/wpml-config.xml          # WPML multilingual config
+```
+
+## Class Architecture (BeTheme)
+
+BeTheme uses a class-per-feature pattern with `mfn_` prefix on all functions:
+
+**Admin classes** (`functions/admin/`):
+- `class-mfn-api.php`, `class-mfn-dashboard.php`, `class-mfn-helper.php`
+- `class-mfn-update.php`, `class-mfn-plugins.php`, `class-mfn-setup.php`
+
+**Builder classes** (`functions/builder/`):
+- `class-mfn-builder.php` — main builder
+- `class-mfn-builder-fields.php` — 2.4MB field definitions
+- `class-mfn-builder-admin.php` — 154KB
+- `class-mfn-builder-front.php` — 136KB
+- `class-mfn-builder-woo-helper.php` — WooCommerce builder integration
+
+**Post type classes** (`functions/post-types/`):
+- `class-mfn-post-type-page.php`, `class-mfn-post-type-product.php`
+- `class-mfn-post-type-template.php` — 84KB
+- 10+ additional post type classes
+
+**Elementor widget classes** (`functions/plugins/elementor/`):
+- `class-mfn-elementor.php` + 80+ widget classes
+
+## WordPress Request Flow
+
+```
+HTTP Request
+    → index.php (defines WP_USE_THEMES = true)
+    → wp-blog-header.php
+    → wp-load.php → wp-config.php (DB + constants)
+    → wp-settings.php (load plugins + theme)
+    → betheme/functions.php (theme init: MFN_THEME_VERSION = 27.6.4)
+    → Loads theme-options.php, theme-functions.php, theme-head.php
+    → WordPress template hierarchy selects template file
+    → WooCommerce hooks modify product/cart/checkout rendering
+```
+
+## WooCommerce Integration Points
+
+1. **Theme support declared** in `theme-woocommerce.php`:
+   - `wc-product-gallery-zoom`, `wc-product-gallery-lightbox`, `wc-product-gallery-slider`
+   - Custom image sizes for thumbnails and single product
+
+2. **Hooks removed** (theme replaces defaults):
+   - `woocommerce_before_main_content` wrappers, breadcrumb, sidebar, sale flash, product thumbnail
+
+3. **Hooks added** (theme enhancements):
+   - Quantity buttons, wishlist button, excerpt in loop, cart fragment AJAX
+
+4. **Template overrides** (`betheme/woocommerce/`):
+   - 27 files override WooCommerce default templates
+
+## Custom Code Locations
+
+| Location | Purpose |
+|----------|---------|
+| `betheme/functions/theme-woocommerce.php` | WooCommerce hooks & filters |
+| `betheme/functions/theme-functions.php` | Theme hooks, helpers, shortcodes |
+| `betheme/woocommerce/` | WooCommerce template overrides |
+| `code-snippets` plugin | DB-stored PHP snippets (admin-managed) |
+| `head-footer-code` plugin | Header/footer injection |
+| `wp-headers-and-footers` plugin | Global header/footer scripts |
+
+## Database
+
+- **Engine:** MariaDB at `mariadb114.miody.nazwa.pl`
+- **Database:** `miody_miodynew`
+- **Table prefix:** `wp_` (default — not hardened)
+- **Custom tables:** None confirmed outside standard WordPress/WooCommerce tables
+- **Schema doc:** `.paul/codebase/db_schema.md`