Memory Wiki

Create the Project Brief for Module 8 (Forms) at /root/.hermes/plans/pb-m8-forms.md. This is a REAL scoping exercise — the old build plan spec is generic CRUD, ignore it. SA needs to design the actual form system. ## Core Requirements (from Profe) ### 1. GUI Form Builder Drag-and-drop form builder (React SPA or similar). User creates forms visually: - Field types: text, email, select, checkbox, radio, textarea, file upload, Stripe iframe, membership tier selector - Conditional logic: show/hide fields based on prior answers - Multi-step forms (wizard-style pages) - Form templates (registration, payment, contact, survey, application) - Drag-and-drop field reordering ### 2. Stripe iframes (PCI offload) Forms need embedded Stripe Elements/Checkout iframes for payment collection. No PCI liability — Stripe handles card data. This means: - Field type: "Stripe Payment" that renders an iframe/Stripe Element - On submit: create Stripe PaymentIntent or Checkout Session via Module 3 (stripe_service) - Handle Stripe webhook response (payment succeeded/failed) to determine form completion ### 3. WP User Creation On form submission with specific trigger: - Create WordPress user account (wp_insert_user / wp_create_user) - This triggers Module 1's ProfeChassis user_register hook → creates profe_users record - Configurable per form: "Create WP user on submit?" checkbox in form admin ### 4. Profe Member Creation After WP user exists: - Assign membership level (free/lite/standard) in profe_users.membership_level - Create subscription record in profe_subscriptions (if paid) - Create order record in profe_orders (if paid) ### 5. CRM Sync (Post-Submit Pipeline) After submission, the form system fires a pipeline: 1. Form submitted → create WP user → Profe chassis syncs to profe_users 2. Enqueue CRM sync via Module 5 (crm_sync): `enqueueContactCreate(userId)` 3. CRM processes → syncs to Brevo → Module 4 mail_queue triggers welcome/confirmation emails 4. If paid: fire conversion tracking via T52 Google Ads ### 6. Email Notifications - Admin notification on form submission - User confirmation/thank-you email - Payment receipt via Module 3 (invoice_manager) + Module 4 (mail_queue) - Configurable email templates per form ### 7. Additional Features - Spam protection: honeypot + reCAPTCHA via InputSanitizerInterface - File uploads via Module 6 (bunny_storage) - Entry management: search, filter, export CSV, delete submissions - Submission analytics: views, starts, completions, conversion rate - Webhook triggers: on form submission fire event for Module 10 automator - Form templates: pre-built registration, payment, contact, survey ## What the PB needs ### Structure ``` # Project Brief: Module 8 — Forms **Document ID:** PB-M8-FORMS-001 **Author:** SA **Date:** 2026-05-25 ## §0 Executive Summary - What forms are (membership funnel front door) - Risk level (MEDIUM — payment + user creation pipeline) - Dependencies across 7 existing modules ## §1 Locked from Past Modules - Identity: profe_users hub, UUID FK - Database: separate profe_main, PDO prepared statements - Security: CSRF on admin, webhook exemption pattern - Module 3: Stripe checkout/sessions for payment forms - Module 4: mail_queue for email notifications - Module 5: crm_sync for post-submit CRM pipeline - Module 6: bunny_storage for file uploads - Module 10: automator for webhook triggers - Past faults: FAULT-001 through FAULT-018 ## §2 Module Breakdown (3 sub-modules) ### T43 — Form Engine (the core) - Form schema CRUD - Conditional logic engine - Multi-step wizard support - GUI builder API endpoints - Field type definitions ### T44 — Form Submissions (the runtime) - Entry storage - Post-submit pipeline runner: 1. Validate inputs 2. Process Stripe payment (if payment field) 3. Create WP user (if configured) 4. Sync to profe_users via chassis 5. Assign membership level 6. Enqueue CRM sync → triggers email 7. Fire conversion tracking 8. Send admin notification - Entry management (search, export, delete) ### T45 — Form Admin (the UI) - React SPA or embedded admin panel - Drag-and-drop form builder - Form settings (email templates, post-submit actions) - Submission viewer - Analytics dashboard ## §3 Database Schema Full DDL for all new tables. Things to consider: - form schemas (field definitions, conditional rules, multi-step pages) - form submissions (form_id, submitter data, payment status, user_id, membership_level) - form analytics (views, starts, completions, conversion funnel) ## §4 Post-Submit Pipeline Design The key architectural decision. Design the pipeline as a series of configurable steps: 1. validate → 2. process_payment → 3. create_user → 4. assign_membership → 5. sync_crm → 6. send_emails → 7. track_conversion → 8. notify_admin Each step should be optional per form. The pipeline should be transactional — if step 3 fails, step 2 should roll back. ## §5 Critical Design Decisions - Stripe iframe vs full Stripe Checkout redirect - WP user creation: wp_insert_user with generated password vs email + set_password - GUI builder: embedded admin panel vs React SPA (follow admin_app architecture from Module 10) - Pipeline rollback strategy - Conditional logic engine (frontend-only vs server-side validation) ## §6 Build Order Dependencies determine order: 1. Form Engine (schema CRUD first — the builder needs it) 2. Form Admin (GUI builder — depends on engine) 3. Form Submissions (runtime — depends on engine + admin is done) ## §7 Risk Assessment ## §8 Forward Signal Items