Folder Structure

Knowing where each subsystem lives is the fastest way to find the class, hook, or template you need to work with. This guide maps the Havenlytics plugin directory for professional WordPress developers: the root files that bootstrap the plugin, the includes/ subdirectories that hold the PSR-4 class tree, the React source in src/, static assets/, compiled build/ output, theme-overridable templates/, and how each folder maps onto the HvnlyNab\ namespace.

Havenlytics maps the HvnlyNab\ namespace via PSR-4 to includes/. That single rule means the folder tree under includes/ is the namespace tree: a class at includes/Workspace/Api/MeController.php is HvnlyNab\Workspace\Api\MeController. Once you internalize that, navigating the codebase becomes mechanical.

Root files

The plugin root holds the entry point and lifecycle files. Everything else is loaded from here.

havenlytics/
├── havenlytics.php          Entry file: constants, shared includes, autoload,
│                            ErrorHandler, ConflictChecker, HvnlyNab singleton.
├── uninstall.php            Data cleanup on uninstall (WP_UNINSTALL_PLUGIN guard).
├── readme.txt               WordPress.org-style plugin readme.
├── README.md                Repository readme.
├── CHANGELOG.md             Version history.
├── composer.json            PSR-4 autoload map (HvnlyNab\ -> includes/).
├── vendor/                  Composer dependencies + generated autoloader.
├── includes/                PSR-4 class tree (HvnlyNab\ namespace root).
├── assets/                  Static CSS, JS, images shipped as-is.
├── build/                   Compiled build output (settings, setup, workspace).
├── templates/              Theme-overridable front-end templates.

Note: havenlytics.php is the only PHP file that runs procedural code at include time. Every class is loaded lazily through the Composer autoloader. See Bootstrap Process for the exact load order.

The includes/ directory

This is the heart of the plugin. Each subdirectory is a bounded subsystem and a namespace segment. The tree below is annotated with the responsibility of each area, grounded in the classes that live there.

includes/
├── Core/            Bootstrap orchestrator, Installer, Scheduler, ErrorHandler,
│                    EnvironmentChecker, ConflictChecker, HookManager, cache classes,
│                    RewriteRulesManager, and the Migration/ + DataPreservation/ engines.
├── Admin/           WordPress admin integration (menus, assets, admin screens).
├── Agent/           Agent CPT (hvnly_agent), agent resolution and admin management.
├── Analytics/       Analytics and reporting subsystem.
├── Api/             REST controllers, type builders, and settings endpoints.
├── Common/          Shared cross-cutting services (e.g. AvatarService).
├── ContactAgent/    Contact-agent inquiry flow and AJAX registration.
├── Database/        Database access layer and table helpers.
├── Email/           Transactional email composition and delivery.
├── Frontend/        Front-end runtime (Frontend service, rendering).
├── Functions/       Procedural shared function files loaded at boot.
├── Integrations/    Third-party integrations (e.g. Integrations/Elementor/).
├── Services/        Standalone service classes.
├── Setup/           Onboarding / demo import engine (SetupInstaller).
├── Workspace/       Agent Workspace SPA back end (Api, Auth, bootstrap, assets).
└── HvnlyEngine.php  The property engine (loaded by Bootstrap::init_engine()).

Core/

The orchestration and infrastructure layer. Bootstrap wires every service; Installer handles install/activate/update; Scheduler registers cron events; HookManager registers runtime WordPress hooks; the cache stack (CacheManager, CacheInvalidator, EnterpriseCache) lives here, as do RewriteRulesManager, ErrorHandler, EnvironmentChecker, and ConflictChecker. The Core/Migration/ and Core/DataPreservation/ subtrees hold the migration handlers and backup/restore machinery.

Agent/

Registers and manages the hvnly_agent custom post type and the hvnly_agent_agency taxonomy, plus resolvers that connect properties and inquiries to agents.

Workspace/

The server side of the Agent Workspace single-page app. Contains Api/ REST controllers (served under the hvnly/v1 namespace), Auth/ for session and identity, and the bootstrap/asset loaders for the SPA.

Api/

REST controllers and type builders for the admin and settings surface, served under the hvnlynab/v1 namespace, including DnD card builders and plugin-info endpoints.

Tip: Havenlytics exposes two REST namespaces — hvnlynab/v1 (admin, settings, builders) and hvnly/v1 (Agent Workspace SPA). Match the namespace to the subsystem folder when extending. See REST API.

src/, assets/, and build/

Front-end code follows the standard WordPress build pattern: authored source in src/, static shipped files in assets/, and compiled bundles in build/.

• src/ — React/JavaScript source for the admin apps and the Agent Workspace SPA (for example src/settings/ components). This is authored code, not loaded directly by WordPress.
• assets/ — static CSS, JavaScript, and images that ship as-is (for example the front-end property-map search script). Referenced via HVNLYNAB_ASSETS_URL.
• build/ — compiled output grouped by app (build/settings/, build/setup/, build/workspace/), each with an *.asset.php manifest of dependencies and version hashes. Referenced via HVNLYNAB_BUILD_URL / HVNLYNAB_BUILD_PATH.

<?php
// Enqueue a compiled Workspace bundle using its generated asset manifest.
$asset = include HVNLYNAB_BUILD_PATH . 'workspace/workspace.asset.php';

wp_enqueue_script(
    'havenlytics-app',
    HVNLYNAB_BUILD_URL . 'workspace/workspace.js',
    $asset['dependencies'],
    $asset['version'],
    true
);

Warning: Never edit files in build/ by hand — they are regenerated from src/ and your changes will be overwritten. Edit the source and rebuild.

templates/

The templates/ folder holds front-end templates that a theme can override. Havenlytics resolves templates from the active or child theme’s havenlytics/ folder before falling back to the plugin’s own templates/. This is the standard, upgrade-safe way to customize markup. See Template Override and Template Loader.

your-theme/
└── havenlytics/            <-- override folder inside the active/child theme
    └── (mirror the template path from the plugin's templates/ folder)

HvnlyNab namespace map

Because the PSR-4 root is includes/, each subdirectory maps to a sub-namespace. Use this table to translate between a class name and its file location.

Note: Shared procedural helpers in includes/Functions/ are plain function files loaded at boot, not namespaced classes. They provide global functions like HVNLY_NAB() and utility helpers.

Best practices

• Locate a class by reading its namespace: strip HvnlyNab\, replace separators with slashes, and look under includes/.
• Reference files through the path constants (HVNLYNAB_PATH, HVNLYNAB_INCLUDES, HVNLYNAB_BUILD_PATH) rather than hardcoding directories.
• Override templates in your theme’s havenlytics/ folder instead of editing plugin files, so upgrades stay clean.
• Treat build/ as generated output; make front-end changes in src/.

Performance recommendations

• Load compiled scripts using the generated *.asset.php manifests so cache-busting versions stay accurate.
• Serve static resources from assets/ via HVNLYNAB_ASSETS_URL to benefit from browser and CDN caching.

Common mistakes

• Editing build/ directly. Those files are overwritten on the next build.
• Placing overrides in the wrong theme folder. The override folder is havenlytics/ inside the active or child theme, not the plugin.
• Hardcoding paths. Use the defined constants so the plugin works regardless of install location.