1. 1. Project Vision & Value Proposition

The core vision of RETROFORM is to eliminate the friction and overhead associated with building and managing form backends. In a world of bloated, complex form builders and time-consuming DIY server setups, RETROFORM offers a streamlined, developer-first alternative.

Value Proposition:

• Simplicity: The primary value is simplicity. Developers can add a robust backend to any HTML form by pointing it to a unique endpoint URL.
• Speed: Go from code to a production-ready form with a dashboard, notifications, and spam protection in minutes, not hours.
• Control: Unlike third-party embeds, RETROFORM allows developers to maintain complete control over their frontend UI/UX.
• Scalability: The serverless architecture, built on Supabase and Cloudflare, handles spikes in traffic without manual intervention.

2. Technology Stack

RETROFORM is built on a modern, scalable, and cost-effective technology stack, chosen to maximize developer productivity and application performance.

• Frontend:
  • React (Vite): For a fast, modern, and efficient single-page application (SPA) development experience.
  • TypeScript: For type safety and improved code quality.
  • Tailwind CSS: For a utility-first CSS workflow that enables rapid and consistent UI development.
  • shadcn/ui: A collection of beautifully designed, accessible, and unstyled components that serve as the building blocks of the UI.
• Backend & Database:
  • Supabase: The all-in-one backend-as-a-service (BaaS) platform providing:
    • PostgreSQL Database: A powerful, open-source relational database.
    • Authentication: Secure user management and row-level security (RLS).
    • Edge Functions: Deno-based serverless functions for all backend logic (e.g., form submission, payment processing).
    • Storage: For securely handling file uploads.
• Payments:
  • Lemon Squeezy: A merchant-of-record platform that simplifies subscription billing and tax compliance.
• Deployment:
  • Cloudflare Pages: For continuous deployment and hosting of the frontend application.
  • Supabase CLI: For managing database migrations and deploying Edge Functions.

3. Architectural Overview

RETROFORM uses a decoupled, serverless architecture. The frontend (React SPA) is completely separate from the backend logic (Supabase Edge Functions).

graph TD
subgraph User Browser
A[React SPA on Cloudflare Pages]
end

subgraph Supabase Platform
B[Supabase Auth]
C[Edge Functions]
D[PostgreSQL Database]
E[Supabase Storage]
end

subgraph Third-Party Services
F[Lemon Squeezy API]
G[Email/WhatsApp Gateway]
end

A -- Manages UI & State --> A
A -- Login/Signup --> B
A -- Invokes for data/actions --> C
A -- Uploads files to --> E

C -- Authenticates via JWT --> B
C -- Reads/Writes data --> D
C -- Stores files --> E
C -- Creates checkout sessions --> F
C -- Sends notifications --> G

F -- Sends webhooks to --> C

Key Architectural Patterns:

• Backend for Frontend (BFF): The Supabase Edge Functions act as a BFF, providing a tailored API for the React frontend. This keeps frontend logic clean and centralizes business logic in the backend.
• Row-Level Security (RLS): PostgreSQL RLS is used extensively to ensure that users can only access and modify data they own. This is a fundamental security principle of the application.
• Stateless Edge Functions: All backend logic is encapsulated in stateless Deno functions, which can be scaled independently.
• Database as the Source of Truth: The Supabase PostgreSQL database is the single source of truth for all user data, forms, submissions, and subscriptions.

4. Feature Implementation Deep Dive

4.1. Form Submission Flow

This is the core feature of the application.

1. Endpoint: Each form is assigned a unique endpoint_slug. The submission URL is https://<your-supabase-url>/functions/v1/submit-form/<endpoint_slug>.
2. submit-form Edge Function: This function is the entry point for all form submissions. It is configured with verify_jwt = false to be publicly accessible.
3. Processing:
   • It retrieves the form settings from the database using the endpoint_slug.
   • It performs spam checks (honeypot, IP-based rate limiting).
   • It saves the submission data (a JSONB object) to the submissions table.
   • If file uploads are present, it handles them via Supabase Storage.
   • Enhanced Notification Triggering: It now evaluates notification_rules associated with the form. Based on these rules, it triggers various notification functions (email, WhatsApp, Discord, webhooks, Google Sheets) either instantly or queues them for digest processing.
4. Response: The function returns a redirect to a "thank you" page or a JSON response, based on the form's settings.

4.2. Enhanced Notification System (Pro Feature)

The new notification system provides unparalleled flexibility and control over how users receive form submission alerts.

1. notification_channels Table: Stores configurations for various notification endpoints (e.g., recipient email, WhatsApp number, Discord webhook URL, advanced webhook settings, Google Sheet ID).
2. notification_templates Table: Allows users to create reusable, customizable templates for notification content (subject, body) using dynamic placeholders ({{formName}}, {{formData.field_name}}).
3. notification_rules Table: Links a specific form to a notification_channel and an optional notification_template. Each rule defines:
   • Digest Frequency: instant, daily, or weekly.
   • Conditions: JSONB object defining criteria based on submission data (e.g., {"field": "priority", "operator": "eq", "value": "high"}).
   • Enabled Status: Whether the rule is active.
4. submit-form Function Integration: After a submission, submit-form queries and evaluates all active notification_rules for that form.
   • If a rule's conditions are met and digest_frequency is instant, it invokes the relevant send-notification-* Edge Function immediately.
   • If digest_frequency is daily or weekly, the submission is added to the digest_queue table.
5. digest_queue Table: Temporarily stores submissions awaiting digest processing.
6. send-notification-digest Edge Function: A scheduled function that processes digest_queue entries, compiles submissions into a single digest message using templates, and then invokes the appropriate send-notification-* function (e.g., send-notification-email) to send the digest.
7. Dedicated Sender Functions:
   • send-notification-email: Sends templated emails via Resend.
   • send-notification-whatsapp: Sends templated WhatsApp messages via Twilio.
   • send-notification-discord: Sends templated messages to Discord webhooks.
   • send-notification-webhook: Sends highly configurable webhooks with custom methods, headers, and templated JSON/form-urlencoded bodies.
   • sync-to-google-sheets: Appends templated row data to Google Sheets.
8. Paywall Enforcement: Row Level Security (RLS) policies on notification_rules and notification_templates restrict access to these advanced features to Pro plan subscribers, ensuring secure and proper feature gating.

4.2. Subscription & Payment Integration

Payments are handled by Lemon Squeezy to offload the complexity of billing and taxes.

1. create-checkout-session Edge Function:
   • When a user clicks "Upgrade," the frontend calls this authenticated edge function.
   • The function sends a request to the Lemon Squeezy API, creating a checkout session. Crucially, it includes the user_id in the checkout_data.custom field.
   • It returns the checkout URL to the frontend, which redirects the user to the payment page.
2. lemonsqueezy-webhook Edge Function:
   • After a successful payment (or any subscription event), Lemon Squeezy sends a webhook to this function.
   • The function verifies the webhook signature to ensure it's from Lemon Squeezy.
   • It parses the webhook payload to get the user_id from the custom data.
   • It updates the subscriptions table in the Supabase database with the new plan, status, and limits. This immediately grants the user access to their new features.

4.3. AI-Powered Insights

The ai_analysis_enabled flag on a form, available on the Pro plan, triggers AI analysis.

• Asynchronous Processing: When a submission arrives for an AI-enabled form, the submit-form function can invoke another function (e.g., analyze-submission).
• AI Integration: This function would connect to an AI provider (like OpenAI or Google's Gemini API), sending the form data for analysis (sentiment, categorization, etc.).
• Storing Insights: The results from the AI are stored in the ai_insights JSONB column of the submissions table, ready to be displayed in the dashboard.

5. Conclusion

RETROFORM is a powerful demonstration of how modern, composable technologies can be used to build a robust, scalable, and feature-rich application with a focus on developer experience. By leveraging a serverless architecture with Supabase and Cloudflare, it provides a high-value service with low operational overhead. The careful design of the database schema, the use of RLS for security, and the seamless integration with third-party services like Lemon Squeezy result in a product that is both powerful for users and maintainable for developers.

6. Future Plans

While RETROFORM is already a powerful tool, there are many opportunities for future growth and improvement:

• Advanced Analytics Dashboard: A dedicated analytics dashboard could provide users with deeper insights into their submission data, including trends, conversion rates, and more detailed AI-powered analysis.
• Team Collaboration: Introducing team accounts would allow multiple users to manage the same set of forms and projects, a crucial feature for larger organizations.
• Advanced Spam Filtering: Integrating more advanced spam filtering techniques, such as CAPTCHA (e.g., hCaptcha, Turnstile) or third-party services like Akismet, would provide an even higher level of protection.
• Notification History/Dashboard: A dedicated dashboard to view logs of all sent notifications, their status, and details for auditing and debugging.