docs: map existing codebase

2026-05-07 10:15:04 +02:00
parent f7afb4e4dc
commit 04de2ac558
9 changed files with 999 additions and 0 deletions
--- a/.paul/codebase/structure.md
+++ b/.paul/codebase/structure.md
@@ -0,0 +1,166 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-05-07
+
+## Directory Layout
+
+```
+luxmed2.pagedev.pl/
+|-- .paul/                         # PAUL project state and codebase documentation
+|-- wp-admin/                      # WordPress admin application (vendor/core)
+|-- wp-includes/                   # WordPress core libraries (vendor/core)
+|-- wp-content/                    # Mutable site layer: themes, plugins, MU plugins, languages, backups
+|   |-- themes/                    # Installed themes
+|   |-- plugins/                   # Installed normal plugins
+|   |-- mu-plugins/                # Must-use plugins loaded automatically
+|   |-- languages/                 # WordPress/plugin translations
+|   `-- backups-dup-pro/           # Duplicator generated backup/installer artifacts
+|-- index.php                      # WordPress frontend entry
+|-- wp-config.php                  # Environment/database configuration with secrets
+|-- wp-*.php                       # WordPress root bootstrap/admin endpoints
+|-- CLAUDE.md                      # Project working rules
+`-- project_backup_2026-03-26_13-38-53.zip # Backup archive artifact
+```
+
+## Directory Purposes
+
+**`wp-admin/`:**
+- Purpose: WordPress admin application.
+- Contains: admin screens, AJAX endpoints, install/update/admin logic.
+- Key files: `wp-admin/admin.php`, `wp-admin/admin-ajax.php`, `wp-admin/index.php`.
+- Modification rule: treat as vendor/core; do not edit directly.
+
+**`wp-includes/`:**
+- Purpose: WordPress core libraries.
+- Contains: bootstrap, template loader, database API, user/session APIs, block/editor support.
+- Key files: `wp-includes/version.php`, `wp-includes/template-loader.php`.
+- Modification rule: treat as vendor/core; do not edit directly.
+
+**`wp-content/themes/`:**
+- Purpose: installed themes.
+- Contains: `hello-elementor`, `twentytwentyfive`, `twentytwentyfour`, `twentytwentythree`.
+- Key files: `wp-content/themes/hello-elementor/functions.php`, `wp-content/themes/hello-elementor/style.css`, `wp-content/themes/hello-elementor/assets/css/custom.scss`.
+
+**`wp-content/themes/hello-elementor/`:**
+- Purpose: primary customized theme candidate.
+- Contains: theme templates, theme bootstrap, admin modules, custom assets.
+- Key files: `functions.php`, `theme.php`, `header.php`, `footer.php`, `assets/css/custom.scss`, `assets/css/custom.css`.
+- Note: `functions.php` references `assets/js/custom.js`, but that file was not found.
+
+**`wp-content/plugins/`:**
+- Purpose: installed WordPress plugins.
+- Contains: Elementor, Elementor Pro, Akismet, Duplicator Pro, Copy & Delete Posts, Lordicon, SVG Support.
+- Key files: plugin main entry files such as `wp-content/plugins/elementor/elementor.php` and `wp-content/plugins/elementor-pro/elementor-pro.php`.
+- Modification rule: treat third-party plugin code as vendor unless explicitly choosing to patch it.
+
+**`wp-content/mu-plugins/`:**
+- Purpose: must-use plugins loaded automatically by WordPress.
+- Contains: `cookie-notice-pro-loader.php` and `cookie-notice-pro/`.
+- Key files: `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php`, `wp-content/mu-plugins/cookie-notice-pro/assets/cookienoticepro.script.js`.
+- This is the main site-specific custom code found in the scan.
+
+**`wp-content/backups-dup-pro/`:**
+- Purpose: Duplicator Pro generated backup/installer working files.
+- Contains: installer logs, restore artifacts, original config copies.
+- Key files: `wp-content/backups-dup-pro/installer/dup-installer-log__c3605a4-03080010.txt`.
+- Treat as generated sensitive state, not source.
+
+## Key File Locations
+
+**Entry Points:**
+- `index.php` - public WordPress frontend entry.
+- `wp-blog-header.php` - loads the WordPress environment.
+- `wp-load.php` - resolves and loads config.
+- `wp-config.php` - environment/database configuration.
+- `wp-login.php` - WordPress login entry.
+- `xmlrpc.php` - legacy XML-RPC entry.
+- `wp-cron.php` - WordPress cron entry.
+
+**Configuration:**
+- `wp-config.php` - DB constants, salts, table prefix, debug flag, Duplicator auth key.
+- `CLAUDE.md` - project rules for future coding sessions.
+- `.paul/config.md` - PAUL configuration.
+
+**Core Logic / Customization:**
+- `wp-content/themes/hello-elementor/functions.php` - theme setup and asset enqueue hooks.
+- `wp-content/themes/hello-elementor/assets/css/custom.scss` - local custom CSS source.
+- `wp-content/themes/hello-elementor/assets/css/custom.css` - compiled/minified local CSS.
+- `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php` - consent/GTM plugin PHP.
+- `wp-content/mu-plugins/cookie-notice-pro/assets/cookienoticepro.script.js` - consent banner frontend logic.
+
+**Testing:**
+- No project-owned test directory or config detected.
+
+**Documentation:**
+- `.paul/PROJECT.md` - business context.
+- `.paul/ROADMAP.md` - planning skeleton.
+- `.paul/STATE.md` - PAUL session state.
+- `.paul/codebase/*.md` - codebase map.
+- `readme.html` - WordPress core documentation, not project-specific docs.
+
+## Naming Conventions
+
+**Files:**
+- WordPress root/core files use `wp-*` naming: `wp-load.php`, `wp-settings.php`.
+- Theme templates use standard WordPress names: `index.php`, `header.php`, `footer.php`, `comments.php`, `sidebar.php`.
+- Theme fragments live under `template-parts/`.
+- Custom assets use descriptive/kebab-case names: `wp-content/themes/hello-elementor/assets/css/custom.scss`, `wp-content/mu-plugins/cookie-notice-pro/assets/cookienoticepro.script.js`.
+
+**Directories:**
+- WordPress conventional directories: `wp-admin/`, `wp-includes/`, `wp-content/`.
+- Plugin/theme directories are lower-case or kebab-case: `hello-elementor`, `elementor-pro`, `copy-delete-posts`, `cookie-notice-pro`.
+
+**Special Patterns:**
+- Hello Elementor functions use `hello_elementor_*` prefixes in `wp-content/themes/hello-elementor/functions.php`.
+- MU plugin custom functions use `cnp_*` prefix in `wp-content/mu-plugins/cookie-notice-pro/cookie-notice-pro.php`.
+- Plugin class files often use `class-*.php`, e.g. `wp-content/plugins/lordicon/includes/class-plugin.php`.
+
+## Where to Add New Code
+
+**New Landing Page Styling:**
+- Primary code: `wp-content/themes/hello-elementor/assets/css/custom.scss`.
+- Compiled output: `wp-content/themes/hello-elementor/assets/css/custom.css`.
+- Verify Elementor selectors against rendered page and mobile breakpoints.
+
+**New Frontend Behavior:**
+- Prefer a site-specific file under `wp-content/themes/hello-elementor/assets/js/` and enqueue from `wp-content/themes/hello-elementor/functions.php`.
+- Note: `assets/js/custom.js` is referenced but missing; create or remove the enqueue deliberately.
+
+**New Always-On Site Logic:**
+- Use `wp-content/mu-plugins/cookie-notice-pro/` only when behavior must always load and is related to consent/GTM.
+- For unrelated custom behavior, prefer a separate MU plugin directory or project-owned plugin rather than editing third-party plugins.
+
+**New Elementor/Form Configuration:**
+- Likely configured in WordPress admin and stored in DB; export/document separately if it must be versioned.
+
+**Tests/Tooling:**
+- No current project-owned setup. If introduced, add root-level tooling and document commands in `.paul/codebase/testing.md` and `CLAUDE.md`.
+
+## Special Directories
+
+**`wp-admin/` and `wp-includes/`:**
+- Purpose: WordPress core.
+- Source: upstream WordPress release.
+- Committed: yes.
+- Handling: avoid direct edits; update through WordPress release process.
+
+**`wp-content/plugins/`:**
+- Purpose: third-party plugin code.
+- Source: installed plugins.
+- Committed: yes.
+- Handling: avoid direct edits unless explicitly patching vendor code.
+
+**`wp-content/backups-dup-pro/`:**
+- Purpose: Duplicator generated restore/backup artifacts.
+- Source: generated by Duplicator.
+- Committed: yes, but should be treated as sensitive generated state.
+
+**`.paul/`:**
+- Purpose: PAUL planning and memory files.
+- Source: generated/maintained by PAUL workflows.
+- Committed: intended.
+
+---
+
+*Structure analysis: 2026-05-07*
+*Update when directory structure changes*