ARCHITECTURE.md
| 1 | # SureForms Architecture Documentation |
| 2 | |
| 3 | ## Table of Contents |
| 4 | |
| 5 | 1. [](#introductionIntroduction](#introduction](#introduction) |
| 6 | 2. [](#system-architectureSystem Architecture](#system-architecture](#system-architecture) |
| 7 | 3. [](#core-componentsCore Components](#core-components](#core-components) |
| 8 | 4. [](#data-flowData Flow](#data-flow](#data-flow) |
| 9 | 5. [](#form-building-processForm Building Process](#form-building-process](#form-building-process) |
| 10 | 6. [](#ai-integrationAI Integration](#ai-integration](#ai-integration) |
| 11 | 7. [](#form-submission-and-processingForm Submission and Processing](#form-submission-and-processing](#form-submission-and-processing) |
| 12 | 8. [](#security-featuresSecurity Features](#security-features](#security-features) |
| 13 | 9. [](#extension-pointsExtension Points](#extension-points](#extension-points) |
| 14 | 10. [](#technical-debt-and-improvement-areasTechnical Debt and Improvement Areas](#technical-debt-and-improvement-areas](#technical-debt-and-improvement-areas) |
| 15 | 11. [](#development-guidelinesDevelopment Guidelines](#development-guidelines](#development-guidelines) |
| 16 | |
| 17 | ## Introduction |
| 18 | |
| 19 | SureForms is a modern WordPress form builder plugin designed to provide an intuitive, no-code form building experience. It leverages WordPress's native block editor (Gutenberg) to create a seamless form building experience that integrates naturally with the WordPress ecosystem. |
| 20 | |
| 21 | ### Key Features |
| 22 | |
| 23 | - **Native WordPress Integration**: Built on top of the WordPress block editor |
| 24 | - **AI-Powered Form Generation**: Create forms quickly using AI suggestions |
| 25 | - **No-Code Flexibility**: Advanced features without requiring coding knowledge |
| 26 | - **Mobile-First Design**: Responsive forms that work across all devices |
| 27 | - **Modern UI/UX**: Clean, intuitive interface for both admins and users |
| 28 | - **Security Features**: Anti-spam protection, GDPR compliance, and data security |
| 29 | - **Extensibility**: Developer-friendly architecture with hooks and filters |
| 30 | |
| 31 | ## System Architecture |
| 32 | |
| 33 | SureForms follows a modular architecture pattern, separating concerns into distinct components that interact through well-defined interfaces. |
| 34 | |
| 35 | ```mermaid |
| 36 | graph TD |
| 37 | A[WordPress Core] --> B[SureForms Plugin] |
| 38 | B --> C[Admin Interface] |
| 39 | B --> D[Form Builder] |
| 40 | B --> E[Form Renderer] |
| 41 | B --> F[Form Processor] |
| 42 | B --> G[Database Layer] |
| 43 | B --> H[AI Integration] |
| 44 | |
| 45 | C --> I[Settings Management] |
| 46 | C --> J[Form Management] |
| 47 | C --> K[Entry Management] |
| 48 | |
| 49 | D --> L[Block Editor Integration] |
| 50 | D --> M[Form Templates] |
| 51 | D --> N[Field Components] |
| 52 | |
| 53 | E --> O[Frontend Rendering] |
| 54 | E --> P[Validation] |
| 55 | |
| 56 | F --> Q[Submission Handler] |
| 57 | F --> R[Email Notifications] |
| 58 | F --> S[Confirmation Handler] |
| 59 | |
| 60 | G --> T[Custom Post Types] |
| 61 | G --> U[Custom Database Tables] |
| 62 | G --> V[Metadata Storage] |
| 63 | |
| 64 | H --> W[AI Form Generator] |
| 65 | H --> X[AI Middleware] |
| 66 | ``` |
| 67 | |
| 68 | ## Core Components |
| 69 | |
| 70 | ### Plugin Loader (`Plugin_Loader`) |
| 71 | |
| 72 | The central initialization class that bootstraps the plugin, registers hooks, and loads core components. It follows a singleton pattern to ensure only one instance exists. |
| 73 | |
| 74 | ### Post Types (`Post_Types`) |
| 75 | |
| 76 | Registers and manages custom post types for forms and entries. Handles the admin UI customizations for these post types. |
| 77 | |
| 78 | ### Form Submit (`Form_Submit`) |
| 79 | |
| 80 | Processes form submissions through REST API endpoints, validates input data, handles file uploads, processes anti-spam measures, and triggers email notifications. |
| 81 | |
| 82 | ### AI Form Builder (`AI_Form_Builder`) |
| 83 | |
| 84 | Integrates with AI services to generate form structures based on user prompts. Communicates with middleware services to process AI requests. |
| 85 | |
| 86 | ### Database Layer |
| 87 | |
| 88 | Custom database tables for storing form entries and related data, separate from the WordPress post tables for better performance and data organization. |
| 89 | |
| 90 | ### Frontend Assets (`Frontend_Assets`) |
| 91 | |
| 92 | Manages the loading of CSS and JavaScript assets for the frontend rendering of forms. |
| 93 | |
| 94 | ### Email Notifications |
| 95 | |
| 96 | Handles the sending of email notifications based on form submissions, with support for multiple notification templates and recipients. |
| 97 | |
| 98 | ## Data Flow |
| 99 | |
| 100 | ### Form Creation Flow |
| 101 | |
| 102 | ```mermaid |
| 103 | sequenceDiagram |
| 104 | participant User |
| 105 | participant WordPress |
| 106 | participant FormBuilder |
| 107 | participant Database |
| 108 | |
| 109 | User->>WordPress: Access Form Builder |
| 110 | WordPress->>FormBuilder: Initialize Builder Interface |
| 111 | FormBuilder->>User: Display Form Builder UI |
| 112 | |
| 113 | alt Manual Form Creation |
| 114 | User->>FormBuilder: Add/Configure Form Fields |
| 115 | FormBuilder->>User: Update UI Preview |
| 116 | else AI-Assisted Creation |
| 117 | User->>FormBuilder: Enter Form Description |
| 118 | FormBuilder->>AI: Send Form Description |
| 119 | AI->>FormBuilder: Return Suggested Form Structure |
| 120 | FormBuilder->>User: Display AI-Generated Form |
| 121 | User->>FormBuilder: Modify/Approve Form |
| 122 | end |
| 123 | |
| 124 | User->>FormBuilder: Save Form |
| 125 | FormBuilder->>Database: Store Form Configuration |
| 126 | Database->>WordPress: Return Form ID |
| 127 | WordPress->>User: Confirm Form Creation |
| 128 | ``` |
| 129 | |
| 130 | ### Form Submission Flow |
| 131 | |
| 132 | ```mermaid |
| 133 | sequenceDiagram |
| 134 | participant User |
| 135 | participant Frontend |
| 136 | participant REST_API |
| 137 | participant Validation |
| 138 | participant AntiSpam |
| 139 | participant Database |
| 140 | participant EmailSystem |
| 141 | |
| 142 | User->>Frontend: Fill Form |
| 143 | Frontend->>User: Validate Client-Side |
| 144 | User->>Frontend: Submit Form |
| 145 | Frontend->>REST_API: POST Form Data |
| 146 | |
| 147 | REST_API->>Validation: Validate Data |
| 148 | Validation->>REST_API: Validation Result |
| 149 | |
| 150 | REST_API->>AntiSpam: Check for Spam |
| 151 | AntiSpam->>REST_API: Spam Check Result |
| 152 | |
| 153 | alt Valid Submission |
| 154 | REST_API->>Database: Store Entry |
| 155 | Database->>REST_API: Entry ID |
| 156 | REST_API->>EmailSystem: Trigger Notifications |
| 157 | EmailSystem->>REST_API: Email Status |
| 158 | REST_API->>Frontend: Success Response |
| 159 | Frontend->>User: Show Confirmation |
| 160 | else Invalid Submission |
| 161 | REST_API->>Frontend: Error Response |
| 162 | Frontend->>User: Show Error Message |
| 163 | end |
| 164 | ``` |
| 165 | |
| 166 | ## Form Building Process |
| 167 | |
| 168 | SureForms uses WordPress's block editor as the foundation for its form builder. This approach provides several advantages: |
| 169 | |
| 170 | 1. **Familiar Interface**: Users already familiar with WordPress's editor can easily adapt |
| 171 | 2. **Native Integration**: Seamless integration with WordPress core functionality |
| 172 | 3. **Extensibility**: Ability to leverage the block ecosystem |
| 173 | |
| 174 | ### Block Structure |
| 175 | |
| 176 | Forms are composed of various block types: |
| 177 | |
| 178 | - **Container Blocks**: Group and organize form fields |
| 179 | - **Field Blocks**: Individual form inputs (text, email, checkbox, etc.) |
| 180 | - **Layout Blocks**: Control the visual arrangement of fields |
| 181 | - **Special Blocks**: Submit buttons, GDPR notices, etc. |
| 182 | |
| 183 | Each block has its own edit and save components, following the WordPress block API pattern. |
| 184 | |
| 185 | ### Form Data Storage |
| 186 | |
| 187 | Form configurations are stored as custom post types with: |
| 188 | |
| 189 | - Post content: Stores the block structure (serialized blocks) |
| 190 | - Post meta: Stores form settings, styling options, and other configuration data |
| 191 | |
| 192 | ## AI Integration |
| 193 | |
| 194 | SureForms features an AI-powered form generation system that allows users to create forms by describing them in natural language. |
| 195 | |
| 196 | ```mermaid |
| 197 | graph TD |
| 198 | A[User Input] --> B[AI Middleware] |
| 199 | B --> C[AI Service] |
| 200 | C --> D[Form Structure Generation] |
| 201 | D --> E[Field Mapping] |
| 202 | E --> F[Block Generation] |
| 203 | F --> G[Form Preview] |
| 204 | G --> H[User Edits] |
| 205 | H --> I[Final Form] |
| 206 | ``` |
| 207 | |
| 208 | ### AI Form Generation Process |
| 209 | |
| 210 | 1. User provides a description of the desired form |
| 211 | 2. The description is sent to the AI middleware |
| 212 | 3. AI analyzes the description and generates a structured form definition |
| 213 | 4. The form definition is mapped to SureForms field types |
| 214 | 5. Blocks are generated and inserted into the editor |
| 215 | 6. User can review and modify the generated form |
| 216 | |
| 217 | ## Form Submission and Processing |
| 218 | |
| 219 | ### Submission Handling |
| 220 | |
| 221 | Form submissions are processed through a custom REST API endpoint that: |
| 222 | |
| 223 | 1. Validates the form data against defined rules |
| 224 | 2. Checks for spam using various methods (honeypot, reCAPTCHA, etc.) |
| 225 | 3. Processes file uploads if present |
| 226 | 4. Stores the submission in the database |
| 227 | 5. Triggers email notifications |
| 228 | 6. Returns appropriate success/error responses |
| 229 | |
| 230 | ### Email Notifications |
| 231 | |
| 232 | The email notification system supports: |
| 233 | |
| 234 | - Multiple notification templates per form |
| 235 | - Dynamic content using smart tags |
| 236 | - HTML email formatting |
| 237 | - Conditional sending based on form data |
| 238 | - Custom headers (CC, BCC, Reply-To) |
| 239 | |
| 240 | ```mermaid |
| 241 | graph TD |
| 242 | A[Form Submission] --> B[Email Notification System] |
| 243 | B --> C{Multiple Recipients?} |
| 244 | C -->|Yes| D[Process Each Recipient] |
| 245 | C -->|No| E[Single Email] |
| 246 | D --> F[Parse Email Template] |
| 247 | E --> F |
| 248 | F --> G[Replace Smart Tags] |
| 249 | G --> H[Apply Email Template] |
| 250 | H --> I[Send Email] |
| 251 | I --> J{Success?} |
| 252 | J -->|Yes| K[Log Success] |
| 253 | J -->|No| L[Log Failure] |
| 254 | ``` |
| 255 | |
| 256 | ## Security Features |
| 257 | |
| 258 | SureForms implements multiple security measures to protect against common vulnerabilities: |
| 259 | |
| 260 | ### Anti-Spam Protection |
| 261 | |
| 262 | - **Honeypot Fields**: Hidden fields to catch automated submissions |
| 263 | - **reCAPTCHA Integration**: Multiple versions of Google reCAPTCHA |
| 264 | - **hCaptcha Support**: Alternative to reCAPTCHA |
| 265 | - **Cloudflare Turnstile**: Modern CAPTCHA alternative |
| 266 | |
| 267 | ### Data Protection |
| 268 | |
| 269 | - **GDPR Compliance**: Options to enable GDPR-compliant data handling |
| 270 | - **Data Encryption**: Sensitive data can be encrypted in storage |
| 271 | - **Auto-Delete Entries**: Automatic deletion of entries after a specified period |
| 272 | |
| 273 | ### Input Validation |
| 274 | |
| 275 | - **Client-Side Validation**: Immediate feedback to users |
| 276 | - **Server-Side Validation**: Thorough validation of all submitted data |
| 277 | - **File Upload Security**: Strict file type and size validation |
| 278 | |
| 279 | ## Extension Points |
| 280 | |
| 281 | SureForms provides several extension points for developers: |
| 282 | |
| 283 | ### WordPress Hooks |
| 284 | |
| 285 | ```php |
| 286 | // Example of filter hook for email notification |
| 287 | add_filter('srfm_email_notification', function($parsed, $submission_data, $item, $form_data) { |
| 288 | // Modify email content or recipients |
| 289 | return $parsed; |
| 290 | }, 10, 4); |
| 291 | |
| 292 | // Example of action hook before form submission |
| 293 | add_action('srfm_before_submission', function($form_data) { |
| 294 | // Perform custom actions before form processing |
| 295 | }); |
| 296 | ``` |
| 297 | |
| 298 | ### JavaScript API |
| 299 | |
| 300 | ```javascript |
| 301 | // Example of extending the form validation |
| 302 | window.sureFormsHooks.addFilter( |
| 303 | 'srfm.validation.rules', |
| 304 | 'my-plugin/custom-validation', |
| 305 | function(rules, fieldData) { |
| 306 | // Add custom validation rules |
| 307 | return rules; |
| 308 | } |
| 309 | ); |
| 310 | ``` |
| 311 | |
| 312 | ## Technical Debt and Improvement Areas |
| 313 | |
| 314 | 1. **Performance Optimization**: |
| 315 | - Lazy loading of form assets |
| 316 | - Improved caching strategies |
| 317 | |
| 318 | 2. **Code Refactoring**: |
| 319 | - Further modularization of components |
| 320 | - Consistent naming conventions |
| 321 | |
| 322 | 3. **Testing Coverage**: |
| 323 | - Increase unit and integration test coverage |
| 324 | - Automated UI testing |
| 325 | |
| 326 | ## Development Guidelines |
| 327 | |
| 328 | ### Coding Standards |
| 329 | |
| 330 | SureForms follows WordPress coding standards with some additional guidelines: |
| 331 | |
| 332 | - PHP: PSR-12 with WordPress-specific adaptations |
| 333 | - JavaScript: ESLint with WordPress configuration |
| 334 | - CSS: Follows WordPress CSS coding standards |
| 335 | |
| 336 | ### Development Workflow |
| 337 | |
| 338 | 1. **Feature Planning**: Document requirements and design |
| 339 | 2. **Development**: Implement features with appropriate tests |
| 340 | 3. **Code Review**: Peer review for quality assurance |
| 341 | 4. **Testing**: Automated and manual testing |
| 342 | 5. **Documentation**: Update technical and user documentation |
| 343 | 6. **Release**: Version tagging and deployment |
| 344 | |
| 345 | ### Version Control |
| 346 | |
| 347 | - Feature branches for new development |
| 348 | - Pull request workflow for code review |
| 349 | - Semantic versioning for releases |
| 350 | |
| 351 | ## Conclusion |
| 352 | |
| 353 | SureForms represents a modern approach to WordPress form building, combining the power of the block editor with advanced features like AI form generation. Its modular architecture and extensive extension points make it both user-friendly and developer-friendly, while its focus on security and performance ensures a reliable experience for all users. |
| 354 | |
| 355 | The plugin continues to evolve with a focus on improving user experience, expanding integration capabilities, and optimizing performance across all devices and platforms. |
| 356 |