Memory Wiki

Write the Module 8 (Forms) Project Brief at /root/.hermes/plans/pb-m8-forms.md. This is a real architecture design — not the old generic CRUD spec. ## Core Requirements ### What Forms Need to Do 1. **GUI Form Builder** — drag-and-drop visual builder. Fields: text, email, select, checkbox, radio, textarea, file upload (via Bunny Storage), Stripe Payment iframe, Membership Tier selector, Billing Interval selector. Conditional logic (show/hide fields based on prior values). Multi-step/wizard. Form templates. 2. **Field Types & Conditional Logic** (the Fluent Forms pattern): - "Membership Tier" field type — renders tiers from mem_levels as select/radio - "Billing Interval" field type — radio buttons (monthly/yearly/one-time) - "Stripe Payment" field type — renders Stripe Elements iframe - Conditional logic in the builder: "When [field] = [value], show [other field]" - Example: tier=Standard → show billing interval. interval=monthly AND tier=Standard → show Stripe iframe. tier=Free → hide all payment fields, just show submit button. 3. **Stripe iframes** (PCI offload) — embedded Stripe Elements/Checkout in the form. No PCI liability. On submit: create Stripe PaymentIntent or Checkout Session via Module 3's stripe_service. Handle Stripe webhook response (payment succeeded/failed). 4. **Post-Submit Pipeline** — configurable per form, each step optional: - Validate fields + conditional rules - Process Stripe payment (if payment field) - Create WP user (wp_insert_user, configurable) - Profe chassis syncs WP user → profe_users (automatic via user_register hook) - Assign membership level in profe_users.membership_level - Create subscription + order records (if paid) - Enqueue CRM sync via Module 5 (crm_sync): `crm_sync->enqueueContactCreate(userId)` - CRM talks to Brevo → Module 4 mail_queue sends notifications - Fire conversion tracking (T52 Google Ads) - Send admin notification email 5. **Abandoned Cart / Funnel Tracking** — Forms saves partial submissions at each step. A cron job checks for entries with status "started" or "payment_pending" older than X hours, marks them "abandoned". Fires `profe/form/abandoned` event → Module 10 automator or CRM recovery email. Payment-stage abandonment caught by Stripe webhooks (checkout.session.expired) in Module 3. 6. **Additional Features:** - Free vs Paid fork: free reg creates user immediately. Paid reg waits for Stripe webhook. - Duplicate detection: check email against profe_users before allowing submission - Form versioning: update a live form. In-progress submissions stay on their schema version. - Embeddable: shortcode or JS snippet to render on any page - Success URL: configurable redirect per form after submission - File uploads via Module 6 (bunny_storage) - Spam protection: honeypot + reCAPTCHA via InputSanitizerInterface - Entry management: search, filter, export CSV, delete - Analytics: views, starts, completions, step-by-step conversion funnel - Email notifications: admin on submit, user confirmation, payment receipts (via Module 4) - Webhook triggers: fire event on submission for Module 10 automator ## Project Brief Structure Write to /root/.hermes/plans/pb-m8-forms.md: ``` # Project Brief: Module 8 — Forms **Document ID:** PB-M8-FORMS-001 **Author:** SA **Date:** 2026-05-25 ## §0 Executive Summary ## §1 Locked from Past Modules ## §2 Module Breakdown (T43 Form Engine, T44 Form Submissions, T45 Form Admin) ## §3 Database Schema (Full DDL) ## §4 Event Definitions ## §5 Post-Submit Pipeline Design ## §6 Critical Design Decisions ## §7 Build Order & Dependencies ## §8 Risk Assessment ## §9 Forward Signal Items ``` ### §0 Executive Summary - Forms is the membership funnel front door - Risk: HIGH (handles payment + user creation + CRM pipeline) - Dependencies: Modules 2, 3, 4, 5, 6, 10 ### §2 Module Breakdown — 3 sub-modules **T43 — Form Engine:** Form schema CRUD. Field type definitions (text, email, select, checkbox, radio, textarea, file_upload, stripe_payment, membership_tier, billing_interval, hidden). Conditional logic engine (field → value → action → target). Multi-step support (page groups). Form templates. API endpoints for the GUI builder. **T44 — Form Submissions:** Entry storage. Post-submit pipeline runner (configurable 8-step pipeline). Payment processing via Module 3. WP user creation. Profe member sync. CRM queue (Module 5). Email triggers (Module 4). Conversion tracking. Abandoned cart detection (cron). Entry management (search, export, delete). **T45 — Form Admin:** React SPA or embedded admin panel. Drag-and-drop form builder UI. Conditional logic visual editor. Form settings (pipeline steps, email templates, success URL). Submission viewer + search. Analytics dashboard (views, starts, completions, conversion funnel, abandonment rate). Template library. ### §3 Database Schema Tables needed: - profe_form_schemas (id, name, description, version, pages JSON, fields JSON, conditional_rules JSON, settings JSON, is_active, created_at, updated_at) - profe_form_versions (id, form_id, version_number, schema_snapshot JSON, created_at) - profe_form_submissions (id, form_id, uuid, user_id NULLABLE, status ENUM(started/completed/failed/pending_payment/abandoned), current_step, form_data JSON, payment_status NULLABLE, payment_intent_id NULLABLE, membership_level NULLABLE, ip_address, user_agent, started_at, completed_at, created_at, updated_at) - profe_form_analytics (id, form_id, event_type ENUM(view/start/step/complete/abandon), step_number NULLABLE, user_id NULLABLE, created_at) Indexes: form_id + status, form_id + created_at, email, uuid. ### §5 Post-Submit Pipeline Design this as an ordered pipeline of configurable steps. Each step has a handler class. Pipeline configuration stored in form schema settings JSON: ```json { "pipeline_steps": [ {"step": "validate", "enabled": true}, {"step": "process_payment", "enabled": true}, {"step": "create_wp_user", "enabled": true}, {"step": "assign_membership", "enabled": true}, {"step": "sync_crm", "enabled": true}, {"step": "send_notifications", "enabled": true}, {"step": "track_conversion", "enabled": false}, {"step": "notify_admin", "enabled": true} ] } ``` Pipeline should be transactional (if user creation fails, payment should be reversible). Use compensation actions for rollback. ### §6 Critical Design Decisions - Conditional logic: store as JSON rules in form schema, evaluate server-side on submission AND client-side for real-time UI updates - Stripe: use embedded Stripe Elements (not redirect to Checkout) for seamless form experience - Payment fork: form_submissions.payment_status = null (no payment needed) / pending (waiting for Stripe) / completed / failed - Abandoned detection: cron job runs every 15 min, checks submissions with status=started or payment_pending older than 1 hour - Form versioning: snapshot schema on each edit. Submissions link to form + implicit version (the schema at time of load) ### §8 Risk Assessment HIGH risk — payment handling + user creation + CRM pipeline. Mitigations: Stripe webhooks handle payment state; pipeline steps are individually configurable; compensation actions for partial failures. ### §9 Forward Signal Items - Stripe Checkout redirect (alternative to embedded iframe) - A/B testing form variants - Webhook receiver for external form submissions (Zapier) - Payment plan / installment support