# Plattio Forms architecture

## Data model

Forms are private `plattio_form` posts. The sanitized form schema is stored in `_plattio_form_schema` as JSON. Entries are stored in the dedicated `{prefix}plattio_forms_entries` table so entry queries do not load WordPress post metadata.

## Runtime components

- `Plattio_Forms`: bootstrap, post type, and retention schedule.
- `Plattio_Forms_Repository`: form and entry persistence plus schema sanitization.
- `Plattio_Forms_Conditional_Logic`: shared rule sanitization and server-side AND/OR evaluation.
- `Plattio_Forms_Renderer`: shortcode rendering, dynamic defaults, initial conditional visibility, and conditional frontend assets.
- `Plattio_Forms_Submissions`: active-field resolution, validation, spam controls, uploads, conditional notifications, and ordered conditional confirmations.
- `Plattio_Forms_Admin`: forms list, templates, builder, entries, settings, and tools.
- `Plattio_Forms_Privacy`: privacy-policy text and WordPress exporter/eraser integrations.
- `Plattio_Forms_I18n`: bundled locale loading and WordPress-core translation fallback.
- `Plattio_Forms_Email_Builder`: optional premium visual email-design storage, safe HTML rendering, per-notification selection, test delivery, and plain-text alternatives.

## Extension point

`plattio_forms_submission_complete` runs after validation, optional entry creation, and notifications. When entry storage is disabled, it runs before temporary uploaded attachments are deleted.

## Module and frontend loading

The always-loaded module manager stores metadata and activation state only. Signature and Multi-Page PHP is required only when each module is active because those modules participate in schema rendering. The larger PDF Documents and Email Builder runtimes are additionally restricted to administrator screens, relevant AJAX/admin-post routes, form submission processing, PDF cleanup cron, and WP-CLI; ordinary frontend page views do not load those classes.

The renderer discovers exact published form IDs in shortcodes, native Gutenberg blocks, nested blocks, and synced patterns before `wp_head`. Plattio Builder performs equivalent discovery in stored layouts and reusable Plattio Blocks. Each schema then requests only core assets and the features it contains: Dashicons, international phone data, Signature assets, and/or Multi-Page assets. A footer compatibility path prints only form styles first requested by legitimate dynamic output after `wp_head`. Site-wide loading remains an explicit opt-in fallback.

## Imported PDF backgrounds

The optional PDF Documents module bundles Mozilla PDF.js locally for administrator-only use. When an administrator selects an existing PDF, its pages are rendered in the browser to high-resolution page images and saved through a nonce- and capability-protected WordPress AJAX endpoint. The original PDF and form data are never sent to a third-party service. Generated entry PDFs use the page images as exact full-page backgrounds and place only fields from the connected form at saved percentage-based coordinates.

## Premium Email Builder

The optional Email Builder stores reusable designs as private `plattio_email_tpl` child posts. Notification configuration contains only the selected design identifier. During notification delivery, a module filter validates that the design is published and belongs to the same form before replacing the message with table-based HTML. PHPMailer receives a generated plain-text `AltBody`. Inactive or unavailable designs fall back to the normal core plain-text notification. See `EMAIL-BUILDER.md`.

## Flatsome UX Builder integration

`Plattio_Forms_Flatsome` registers the existing `plattio_form` shortcode through Flatsome’s public `ux_builder_setup` and `add_ux_builder_shortcode()` integration points. The integration remains inside Plattio Forms, so theme updates do not overwrite it. Published forms are queried when UX Builder starts and are exposed as selectable shortcode options. The content iframe receives normal frontend assets and active form-module assets, while dynamically inserted form markup is initialized through the same frontend runtime used on public pages.


## Gutenberg integration

`Plattio_Forms_Gutenberg` registers the dynamic `plattio-forms/form` block from `blocks/form/block.json`. The editor receives a localized list of published forms and stores only the selected form ID plus title/description visibility overrides as block attributes. The editor preview uses WordPress server-side block rendering against the canonical `[plattio_form]` shortcode callback, while form controls are disabled inside the editor to prevent accidental submissions. On public singular views, `Plattio_Forms_Renderer` detects nested form blocks before output starts and enqueues the core and schema-specific module assets early enough for normal head/footer loading.
