# mr-bappi/cloudfold architecture

> Architecture diagram of the GitHub repository mr-bappi/cloudfold, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-bappi/cloudfold
- Repository: https://github.com/mr-bappi/cloudfold

## Overview

1. **What this repository is**
   PixNest Pro is a WordPress plugin, not a standalone app. The runtime entrypoint is `pixnest-pro.php`, which boots a PHP plugin stack under `includes/` and wires it into WordPress via the usual plugin lifecycle.

2. **Main runtime boundaries**
   The code is split into three primary planes:
   - **PHP plugin backend** in `includes/`
   - **Admin experience** in `admin/js/src/` with compiled assets in `admin/dist/`
   - **Public rendering/assets** in `public/` plus server-side block/shortcode renderers in `blocks/`
   This separation is important: admin authoring, frontend display, and core business logic are distinct layers.

3. **Core plugin orchestration**
   `includes/class-pixnest.php`, `class-pixnest-loader.php`, and the activator/deactivator classes handle plugin bootstrapping, hook registration, and lifecycle tasks. This is the central coordination layer that connects all feature modules to WordPress actions, filters, REST routes, AJAX, and asset loading.

4. **Content and media management subsystem**
   Gallery and media organization are modeled through dedicated backend components such as:
   - `includes/admin/class-pixnest-gallery-cpt.php`
   - `includes/admin/class-pixnest-media-organizer.php`
   - `includes/core/class-pixnest-gallery-manager.php`
   - `includes/core/class-pixnest-smart-organizer.php`
   - `includes/core/class-pixnest-db.php`
   These modules manage galleries, albums, folder hierarchies, ordering, captions, links, and related metadata.

5. **Admin UI architecture**
   The admin dashboard is a React application under `admin/js/src/` with a root `App.jsx`, shared context in `store/AppContext.js`, API access through `hooks/useApi.js`, and feature panels for galleries, folders, settings, licensing, and AI tools. Compiled output is shipped in `admin/dist/`, so the browser consumes static bundles while PHP provides data and endpoints.

6. **Server-to-admin data flow**
   The admin React UI does not talk directly to storage; it uses WordPress-backed endpoints exposed by `includes/admin/class-pixnest-rest-api.php` and `class-pixnest-ajax.php`. That means the flow is:
   admin UI → REST/AJAX → PHP service layer → WordPress data/storage → response back to React.
   This is the main editing/control path for galleries and settings.

7. **Public rendering path**
   Frontend output is produced by shortcode and block renderers in `includes/public/class-pixnest-shortcode.php` and `blocks/*/render.php`. The plugin also ships public JS/CSS under `public/` for gallery layouts, lightbox, hotspots, proofing, and video galleries. The public side is designed to load assets on demand rather than globally.

8. **Gutenberg/block subsystem**
   Each gallery layout has a corresponding block folder (`gallery`, `masonry`, `justified`, `carousel`, `lightbox`, `album`) with `block.json`, editor JS, render PHP, and scoped CSS. This means block editing happens in JavaScript, while final HTML can still be rendered server-side for consistency and SEO.

9. **Feature engines inside `includes/core/`**
   The core feature modules are organized as independent engines: layout rendering, lightbox, hotspots, proofing, smart crop, video gallery, optimizer, cloud offload, and WooCommerce integration. These are not separate apps; they are reusable service modules called by admin, block renderers, or public rendering paths depending on the feature being used.

10. **AI integration architecture**
    AI is abstracted behind a provider interface/factory in `includes/providers/`, with concrete implementations for Claude, OpenAI, Gemini, and OpenRouter. `includes/core/class-pixnest-ai.php` likely coordinates the higher-level AI workflows such as alt text, tagging, and bulk enrichment, while the provider layer handles vendor-specific API differences.

11. **Commerce and special integrations**
    WooCommerce support lives in `includes/core/class-pixnest-woocommerce.php`, indicating hooks into product galleries and zoom/lightbox behavior rather than a separate commerce module. Likewise, licensing is isolated under `includes/licensing/`, keeping activation and entitlement checks away from gallery logic.

12. **Build and distribution structure**
    The repo includes source and packaged outputs side by side. `admin/js/src/` is the source for the admin bundle, `vite.config.js` and `scripts/build.js` support compilation, and `release/pixnest-pro/` is a packaged plugin snapshot with built assets and docs. That release tree mirrors the runtime structure and is what would be shipped to users.

13. **Documentation and validation ecosystem**
    `docs/`, `planning/`, `tests/`, and `website/` are supporting layers rather than runtime components. They document features, define release plans, and contain smoke tests plus a docs site/marketing pages. These folders matter for delivery confidence, but they are not part of the plugin execution path.

14. **Overall architecture in one sentence**
    PixNest Pro is a WordPress plugin with a PHP service core, a React-based admin console, server-rendered Gutenberg/shortcode outputs, and modular feature engines for media management, AI, performance, and WooCommerce, all connected through WordPress hooks, REST/AJAX, and enqueued frontend assets.

Main entry points: [`includes/class-pixnest.php`](https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest.php) (Core Plugin), [`includes/core/class-pixnest-layout-engine.php`](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-layout-engine.php) (Layout Engine), [`includes/admin/class-pixnest-rest-api.php`](https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-rest-api.php) (Admin API), [`includes/core/class-pixnest-gallery-manager.php`](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-gallery-manager.php) (Gallery Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Plugin Runtime"]
  node_pixnest_entry["PixNest Pro<br/>plugin entry<br/>[pixnest-pro.php]"]
  node_pixnest_core["Core Plugin<br/>orchestrator<br/>[class-pixnest.php]"]
  node_pixnest_loader["Loader<br/>hook registry"]
  node_pixnest_lifecycle["Lifecycle<br/>activation"]
end

subgraph group_admin["Admin Experience"]
  node_pixnest_admin_api["Admin API<br/>wp endpoints"]
  node_pixnest_admin_backend["Admin Backend<br/>wp admin"]
  node_admin_app["Admin App<br/>react ui<br/>[App.jsx]"]
  node_admin_store["App State<br/>react context<br/>[AppContext.js]"]
  node_admin_api_hook["API Hook<br/>client api<br/>[useApi.js]"]
end

subgraph group_public["Public Delivery"]
  node_public_boot["Public Boot<br/>frontend loader"]
  node_shortcode["Shortcode<br/>render entry"]
  node_blocks["Block Suite<br/>gutenberg blocks<br/>[render.php]"]
end

subgraph group_engines["Feature Engines"]
  node_gallery_manager["Gallery Manager<br/>content service"]
  node_media_org["Media Organizer<br/>taxonomy service"]
  node_db[("DB Layer<br/>storage")]
  node_layout_engine["Layout Engine<br/>render engine"]
  node_ai_core["AI Core<br/>ai workflows"]
  node_ai_providers["AI Providers<br/>provider factory"]
  node_license["Licensing<br/>entitlement"]
  node_woocommerce["WooCommerce<br/>commerce integration"]
end

subgraph group_tooling["Build & Release"]
  node_release_pkg["Release Package<br/>distribution snapshot<br/>[pixnest-pro.php]"]
  node_docs_site["Docs Site<br/>documentation<br/>[index.md]"]
end

node_pixnest_entry -->|"boots"| node_pixnest_core
node_pixnest_core -->|"registers"| node_pixnest_loader
node_pixnest_core -->|"activates"| node_pixnest_lifecycle
node_pixnest_core -->|"adds admin"| node_pixnest_admin_backend
node_pixnest_core -->|"adds frontend"| node_public_boot
node_pixnest_admin_backend -->|"exposes"| node_pixnest_admin_api
node_admin_app -->|"calls"| node_admin_api_hook
node_admin_app -->|"shares state"| node_admin_store
node_admin_api_hook -->|"requests"| node_pixnest_admin_api
node_pixnest_admin_api -->|"serves"| node_gallery_manager
node_pixnest_admin_api -->|"serves"| node_media_org
node_gallery_manager -->|"persists"| node_db
node_media_org -->|"persists"| node_db
node_shortcode -->|"renders"| node_layout_engine
node_blocks -->|"renders"| node_layout_engine
node_public_boot -->|"loads"| node_layout_engine
node_layout_engine -->|"reads"| node_gallery_manager
node_ai_core -->|"uses"| node_ai_providers
node_ai_core -->|"enriches"| node_gallery_manager
node_license -->|"guards"| node_pixnest_core
node_woocommerce -->|"extends"| node_layout_engine
node_release_pkg -.->|"packages"| node_pixnest_entry
node_docs_site -.->|"documents"| node_pixnest_core

click node_pixnest_entry "https://github.com/mr-bappi/cloudfold/blob/main/pixnest-pro.php"
click node_pixnest_core "https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest.php"
click node_pixnest_loader "https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest-loader.php"
click node_pixnest_lifecycle "https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest-activator.php"
click node_pixnest_admin_api "https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-rest-api.php"
click node_pixnest_admin_backend "https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-admin.php"
click node_admin_app "https://github.com/mr-bappi/cloudfold/blob/main/admin/js/src/App.jsx"
click node_admin_store "https://github.com/mr-bappi/cloudfold/blob/main/admin/js/src/store/AppContext.js"
click node_admin_api_hook "https://github.com/mr-bappi/cloudfold/blob/main/admin/js/src/hooks/useApi.js"
click node_public_boot "https://github.com/mr-bappi/cloudfold/blob/main/includes/public/class-pixnest-public.php"
click node_shortcode "https://github.com/mr-bappi/cloudfold/blob/main/includes/public/class-pixnest-shortcode.php"
click node_blocks "https://github.com/mr-bappi/cloudfold/blob/main/blocks/gallery/render.php"
click node_gallery_manager "https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-gallery-manager.php"
click node_media_org "https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-media-organizer.php"
click node_db "https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-db.php"
click node_layout_engine "https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-layout-engine.php"
click node_ai_core "https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-ai.php"
click node_ai_providers "https://github.com/mr-bappi/cloudfold/blob/main/includes/providers/class-pixnest-ai-provider-factory.php"
click node_license "https://github.com/mr-bappi/cloudfold/blob/main/includes/licensing/class-pixnest-license.php"
click node_woocommerce "https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-woocommerce.php"
click node_release_pkg "https://github.com/mr-bappi/cloudfold/blob/main/release/pixnest-pro/pixnest-pro.php"
click node_docs_site "https://github.com/mr-bappi/cloudfold/blob/main/docs/index.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pixnest_entry,node_pixnest_core,node_pixnest_loader,node_pixnest_lifecycle toneBlue
class node_pixnest_admin_api,node_pixnest_admin_backend,node_admin_app,node_admin_store,node_admin_api_hook toneAmber
class node_public_boot,node_shortcode,node_blocks toneMint
class node_gallery_manager,node_media_org,node_db,node_layout_engine,node_ai_core,node_ai_providers,node_license,node_woocommerce toneRose
class node_release_pkg,node_docs_site toneIndigo
```

## Components

### Plugin Runtime

WordPress-facing PHP entrypoint and lifecycle orchestration

- [PixNest Pro](https://github.com/mr-bappi/cloudfold/blob/main/pixnest-pro.php): plugin entry · Main plugin bootstrap for WordPress lifecycle startup. · `pixnest-pro.php`
- [Core Plugin](https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest.php): orchestrator · Registers hooks and wires the plugin subsystems together. · `includes/class-pixnest.php`
- [Loader](https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest-loader.php): hook registry · Central hook registration and dispatch helper. · `includes/class-pixnest-loader.php`
- [Lifecycle](https://github.com/mr-bappi/cloudfold/blob/main/includes/class-pixnest-activator.php): activation · Activation and deactivation routines for plugin setup and cleanup. · `includes/class-pixnest-activator.php`

### Admin Experience

React admin app plus WordPress-backed endpoints

- [Admin API](https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-rest-api.php): wp endpoints · REST and AJAX endpoints used by the admin UI. · `includes/admin/class-pixnest-rest-api.php`
- [Admin Backend](https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-admin.php): wp admin · Admin-side WordPress integration, screens, and media organizer wiring. · `includes/admin/class-pixnest-admin.php`
- [Admin App](https://github.com/mr-bappi/cloudfold/blob/main/admin/js/src/App.jsx): react ui · Root React application for the dashboard and settings experience. · `admin/js/src/App.jsx`
- [App State](https://github.com/mr-bappi/cloudfold/blob/main/admin/js/src/store/AppContext.js): react context · Shared admin state and UI data flow. · `admin/js/src/store/AppContext.js`
- [API Hook](https://github.com/mr-bappi/cloudfold/blob/main/admin/js/src/hooks/useApi.js): client api · Browser-side API access wrapper for WordPress-backed requests. · `admin/js/src/hooks/useApi.js`

### Public Delivery

Shortcodes, blocks, and frontend assets

- [Public Boot](https://github.com/mr-bappi/cloudfold/blob/main/includes/public/class-pixnest-public.php): frontend loader · Enqueues and configures frontend rendering assets. · `includes/public/class-pixnest-public.php`
- [Shortcode](https://github.com/mr-bappi/cloudfold/blob/main/includes/public/class-pixnest-shortcode.php): render entry · Server-side shortcode rendering for gallery output. · `includes/public/class-pixnest-shortcode.php`
- [Block Suite](https://github.com/mr-bappi/cloudfold/blob/main/blocks/gallery/render.php): gutenberg blocks · Server-rendered block implementations for gallery layouts. · `blocks/gallery/render.php`

### Feature Engines

Core media, AI, and integration services

- [Gallery Manager](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-gallery-manager.php): content service · Coordinates gallery, album, and ordering logic. · `includes/core/class-pixnest-gallery-manager.php`
- [Media Organizer](https://github.com/mr-bappi/cloudfold/blob/main/includes/admin/class-pixnest-media-organizer.php): taxonomy service · Folder and media organization support for the admin workflow. · `includes/admin/class-pixnest-media-organizer.php`
- [DB Layer](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-db.php): storage · Database access and persistence for plugin data. · `includes/core/class-pixnest-db.php`
- [Layout Engine](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-layout-engine.php): render engine · Generates gallery layouts and display structure. · `includes/core/class-pixnest-layout-engine.php`
- [AI Core](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-ai.php): ai workflows · High-level AI workflows such as enrichment and tagging. · `includes/core/class-pixnest-ai.php`
- [AI Providers](https://github.com/mr-bappi/cloudfold/blob/main/includes/providers/class-pixnest-ai-provider-factory.php): provider factory · Vendor-specific AI provider abstraction and implementations. · `includes/providers/class-pixnest-ai-provider-factory.php`
- [Licensing](https://github.com/mr-bappi/cloudfold/blob/main/includes/licensing/class-pixnest-license.php): entitlement · License validation and activation checks. · `includes/licensing/class-pixnest-license.php`
- [WooCommerce](https://github.com/mr-bappi/cloudfold/blob/main/includes/core/class-pixnest-woocommerce.php): commerce integration · Commerce hooks for product galleries and zoom/lightbox behavior. · `includes/core/class-pixnest-woocommerce.php`

### Build & Release

Source, packaging, and support artifacts

- [Release Package](https://github.com/mr-bappi/cloudfold/blob/main/release/pixnest-pro/pixnest-pro.php): distribution snapshot · Packaged plugin build used for shipping. · `release/pixnest-pro/pixnest-pro.php`
- [Docs Site](https://github.com/mr-bappi/cloudfold/blob/main/docs/index.md): documentation · Supporting documentation and website content. · `docs/index.md`

## Connections

- PixNest Pro → Core Plugin: boots · Plugin bootstrap instantiates the main runtime object.
- Core Plugin → Loader: registers · Core wiring delegates hooks and callbacks to the loader.
- Core Plugin → Lifecycle: activates · Lifecycle handlers are connected during plugin setup.
- Core Plugin → Admin Backend: adds admin · Core registers the WordPress admin layer.
- Core Plugin → Public Boot: adds frontend · Core wires public assets and display hooks.
- Admin Backend → Admin API: exposes · Admin backend publishes REST and AJAX endpoints.
- Admin App → API Hook: calls · React UI uses the browser API hook for data access.
- Admin App → App State: shares state · UI panels coordinate through common app context.
- API Hook → Admin API: requests · Client requests flow into WordPress-backed endpoints.
- Admin API → Gallery Manager: serves · Endpoints invoke gallery and content services.
- Admin API → Media Organizer: serves · Admin operations for folders and media use organizer services.
- Gallery Manager → DB Layer: persists · Gallery state and metadata are stored through the database layer.
- Media Organizer → DB Layer: persists · Organizer data and relationships are written to storage.
- Shortcode → Layout Engine: renders · Shortcodes render galleries through the layout engine.
- Block Suite → Layout Engine: renders · Block renderers reuse the layout engine for final output.
- Public Boot → Layout Engine: loads · Frontend asset loading is tied to the rendering engine.
- Layout Engine → Gallery Manager: reads · Layout rendering consumes gallery model data.
- AI Core → AI Providers: uses · AI workflows select a provider implementation through the factory.
- AI Core → Gallery Manager: enriches · AI features augment gallery metadata and content.
- Licensing → Core Plugin: guards · License checks gate plugin features and activation paths.
- WooCommerce → Layout Engine: extends · Commerce integration modifies gallery presentation behavior.
- Release Package → PixNest Pro: packages · Release tree mirrors the runtime plugin entry and shipped structure.
- Docs Site → Core Plugin: documents · Documentation describes the runtime architecture and workflows.
