# quillforms/quillforms architecture

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

- Interactive diagram: https://gitdiagram.com/quillforms/quillforms
- Repository: https://github.com/quillforms/quillforms

## Overview

##### Project Type & Purpose
- Quill Forms is an open-source, self-hosted “Typeform alternative” implemented as a WordPress plugin plus a standalone React/TypeScript library (monorepo managed by Lerna).
- It provides a drag-and-drop form builder (admin UI in React) and a dynamic form renderer (client-side React) that communicates with a PHP-based backend via WP REST API.

##### High-Level Components
A. Docker & DevOps
- docker-compose.yml orchestrates two containers:
– PHP/WordPress container (runs MySQL, Apache/Nginx, WordPress + QuillForms plugin)
– Node container (for local builds, Lerna, webpack, Babel, TypeScript)
- Build scripts (packages/scripts folder) invoked inside the Node container.
B. WordPress + PHP Backend
- quillforms.php: Plugin bootstrap that registers hooks.
- includes/: Core PHP classes – plugin loader, REST controllers (includes/rest-api), data models, entry processing, payment gateways, compatibility adapters, installers, logger, import/export.
- composer.json / vendor/: PHP dependencies autoloaded.
- DB: Uses WordPress’s MySQL database to store forms, entries, settings, logs, coupons, etc.
C. Frontend React Admin UI (client/)
- client/index.js: Entry point for the React SPA loaded in WP admin.
- client/components & pages/: Form builder UI—blocks panel, sidebar, pages for settings, integrations, payments, results, system.
- CSS/SCSS assets extracted via Webpack and mini-CSS-extract-plugin.
- Communicates to PHP backend via WP REST API endpoints (e.g., /wp-json/quillforms/v1/…).
D. Monorepo Packages (packages/)
- builder-core, builder-panels, block-editor, admin-components, code-editor, document-editor, form-integrations, payment-gateways, renderer-core, react-renderer-utils, rest-fields, settings-editor, theme-editor, types, utils, etc.
- Each is a self-contained npm package (TypeScript or JavaScript) used to build aspects of the UI and renderer.
- Lerna manages inter-package dependencies, versioning, and bootstrapping.
E. Client-Side Renderer
- Built from renderer-core + react-renderer-utils + rest-fields: Generates the public-facing form embed (via iframe or inline) on WP front-end or any React/Next.js app.
- Exposes React Hooks and components for embedding in external React applications (Next.js support).

##### Data Flows & Interactions
1. Admin loads WP → plugin enqueues React admin bundle.
2. React admin UI performs CRUD via REST API: fetch form definitions, save settings, manage payments, view entries.
3. PHP REST controllers handle requests, validate, read/write to MySQL via WP APIs.
4. For public forms, WP shortcode or iframe embed loads the JS renderer bundle (standalone React) → fetch form schema via REST → render and submit entries back to PHP.
5. Payments flow: renderer triggers external payment gateway (Stripe, PayPal, etc.) via client-side SDK or redirects → upon success, PHP records transaction.
6. Docker/Node build pipeline watches packages, compiles TS → outputs to lib/ and client/assets → PHP enqueues those.

##### Architectural Patterns & Design Principles
- Monorepo with Lerna: modular packages sharing types and utilities
- Plugin architecture (WordPress hooks/filters + REST controllers)
- Component-based UI (React + Context/Redux-style stores)
- Separation of concerns: Admin UI vs. Renderer vs. Back-end
- API-driven: All state persists via REST endpoints, enabling headless use
- Build pipeline decoupled via Docker: isolation of PHP and Node environments

##### Detail Level
- Drill into PHP layer: show REST controllers, model classes, plugin hooks.
- Drill into React layer: show store/context providers, main pages (builder, results, settings).
- Don’t overcrowd; group similar packages under “Monorepo Packages” cluster but call out major ones (builder-core, renderer-core, form-integrations).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer entry
    Dev["Developer"]:::external

    %% Docker & DevOps
    subgraph "Docker & DevOps"
        DC[".docker/docker-compose.yml"]:::build
        NDocker["Node Container"]:::build
        PContainer["PHP/WordPress Container"]:::build
        DC --> NDocker
        DC --> PContainer

        %% Node Container internals
        subgraph "Node Container Tools"
            Lerna["Lerna"]:::build
            Webpack["Webpack/Babel/TypeScript"]:::build
            BuildScripts["packages/scripts/"]:::build
        end
        NDocker --> Lerna
        NDocker --> Webpack
        NDocker --> BuildScripts

        %% Build output
        StaticAssets["Static Assets (lib/, client/assets)"]:::build
        Webpack --> StaticAssets
        StaticAssets -->|"enqueue_asset via"| PContainer
    end

    %% Monorepo Packages
    subgraph "Monorepo Packages"   
        BP["packages/builder-core"]:::build
        RP["packages/renderer-core"]:::build
        RI["packages/react-renderer-utils"]:::build
        RF["packages/rest-fields"]:::build
        FI["packages/form-integrations"]:::build
        PG["packages/payment-gateways"]:::build
        AC["packages/admin-components"]:::build
        BPan["packages/builder-panels"]:::build
        BE["packages/block-editor"]:::build
        CE["packages/code-editor"]:::build
        DE["packages/document-editor"]:::build
        ME["packages/messages-editor"]:::build
        NE["packages/notifications-editor"]:::build
        SE["packages/settings-editor"]:::build
        TE["packages/theme-editor"]:::build
        TY["packages/types"]:::build
        UT["packages/utils"]:::build
    end
    Lerna --> BP
    Lerna --> RP
    Lerna --> RI
    Lerna --> RF
    Lerna --> FI
    Lerna --> PG
    Lerna --> AC
    Lerna --> BPan
    Lerna --> BE
    Lerna --> CE
    Lerna --> DE
    Lerna --> ME
    Lerna --> NE
    Lerna --> SE
    Lerna --> TE
    Lerna --> TY
    Lerna --> UT

    %% PHP Backend
    subgraph "WordPress + PHP Backend"
        PHPPlugin["quillforms.php"]:::backend
        Autoload["includes/autoload.php"]:::backend
        ClassQF["includes/class-quillforms.php"]:::backend
        RestAPI["includes/rest-api"]:::backend
        Models["includes/models"]:::backend
        OtherIncludes["includes/entries, addon, payments, import-export, log-handlers, compatibility, system-status"]:::backend
        Composer["composer.json / vendor/"]:::backend
        AssetsEnqueue["lib/client-assets.php"]:::backend
        MySQLDB["MySQL Database"]:::storage

        PHPPlugin --> Autoload
        PHPPlugin --> ClassQF
        ClassQF --> RestAPI
        ClassQF --> Models
        ClassQF --> OtherIncludes
        Composer --> PHPPlugin
        StaticAssets --> AssetsEnqueue
        AssetsEnqueue -->|"enqueues assets"| OutAdmin
        RestAPI --> MySQLDB
        MySQLDB --> RestAPI
    end

    %% Frontend Admin UI
    subgraph "Admin UI (WP Admin)"
        OutAdmin["Browser (Admin)"]:::frontend
        ReactAdmin["React Admin UI"]:::frontend
        ClientIndex["client/index.js"]:::frontend
        CompUI["client/components"]:::frontend
        PagesUI["client/pages"]:::frontend
        StyleUI["client/style.scss"]:::frontend

        OutAdmin --> ReactAdmin
        ReactAdmin --> ClientIndex
        ReactAdmin --> CompUI
        ReactAdmin --> PagesUI
        ReactAdmin --> StyleUI
        ReactAdmin -->|"REST JSON quillforms/v1"| RestAPI
    end

    %% Public Renderer
    subgraph "Public Renderer"
        OutPublic["Browser (Public)"]:::frontend
        RendererUI["React Renderer"]:::frontend
        OutPublic --> RendererUI
        RendererUI --> RP
        RendererUI --> RI
        RendererUI --> RF
        RendererUI -->|"REST JSON quillforms/v1"| RestAPI
    end

    %% External Services
    subgraph "External Services"
        Stripe["Stripe"]:::external
        PayPal["PayPal"]:::external
    end
    RendererUI -->|SDK/redirect| Stripe
    RendererUI -->|SDK/redirect| PayPal
    Stripe -->|webhook| RestAPI
    PayPal -->|webhook| RestAPI

    %% Connections from Dev
    Dev --> DC

    %% Click Events
    click DC "https://github.com/quillforms/quillforms/blob/master/.docker/docker-compose.yml"
    click NDocker "https://github.com/quillforms/quillforms/blob/master/.docker/node.dockerfile"
    click PContainer "https://github.com/quillforms/quillforms/blob/master/.docker/wordpress.dockerfile"
    click BuildScripts "https://github.com/quillforms/quillforms/tree/master/packages/scripts/"
    click PHPPlugin "https://github.com/quillforms/quillforms/blob/master/quillforms.php"
    click Autoload "https://github.com/quillforms/quillforms/blob/master/includes/autoload.php"
    click ClassQF "https://github.com/quillforms/quillforms/blob/master/includes/class-quillforms.php"
    click RestAPI "https://github.com/quillforms/quillforms/tree/master/includes/rest-api/"
    click Models "https://github.com/quillforms/quillforms/tree/master/includes/models/"
    click AssetsEnqueue "https://github.com/quillforms/quillforms/blob/master/lib/client-assets.php"
    click ClientIndex "https://github.com/quillforms/quillforms/blob/master/client/index.js"
    click CompUI "https://github.com/quillforms/quillforms/tree/master/client/components/"
    click PagesUI "https://github.com/quillforms/quillforms/tree/master/client/pages/"
    click StyleUI "https://github.com/quillforms/quillforms/blob/master/client/style.scss"
    click BP "https://github.com/quillforms/quillforms/tree/master/packages/builder-core/"
    click RP "https://github.com/quillforms/quillforms/tree/master/packages/renderer-core/"
    click RI "https://github.com/quillforms/quillforms/tree/master/packages/react-renderer-utils/"
    click RF "https://github.com/quillforms/quillforms/tree/master/packages/rest-fields/"
    click FI "https://github.com/quillforms/quillforms/tree/master/packages/form-integrations/"
    click PG "https://github.com/quillforms/quillforms/tree/master/packages/payment-gateways/"
    click AC "https://github.com/quillforms/quillforms/tree/master/packages/admin-components/"
    click BPan "https://github.com/quillforms/quillforms/tree/master/packages/builder-panels/"
    click BE "https://github.com/quillforms/quillforms/tree/master/packages/block-editor/"
    click CE "https://github.com/quillforms/quillforms/tree/master/packages/code-editor/"
    click DE "https://github.com/quillforms/quillforms/tree/master/packages/document-editor/"
    click ME "https://github.com/quillforms/quillforms/tree/master/packages/messages-editor/"
    click NE "https://github.com/quillforms/quillforms/tree/master/packages/notifications-editor/"
    click SE "https://github.com/quillforms/quillforms/tree/master/packages/settings-editor/"
    click TE "https://github.com/quillforms/quillforms/tree/master/packages/theme-editor/"
    click TY "https://github.com/quillforms/quillforms/tree/master/packages/types/"
    click UT "https://github.com/quillforms/quillforms/tree/master/packages/utils/"

    %% Styles
    classDef build fill:#cfe2f3,stroke:#000
    classDef backend fill:#d9ead3,stroke:#000
    classDef frontend fill:#fce5cd,stroke:#000
    classDef external fill:#ead1dc,stroke:#000
    classDef storage fill:#fff2cc,stroke:#000
```
