Funnel & Page Management

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/funnels/domain/entities/funnel.py
• backend/src/funnels_pages/domain/entities/page.py
• specs/funnels/builder.yaml
• FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md
• FUNNELS_QUICK_START.md

The Funnel & Page Management module is a core component of the marketing automation platform, providing tools for creating, structuring, and deploying high-conversion sales funnels and landing pages. This module follows a Domain-Driven Design (DDD) architecture, separating core business logic (entities and value objects) from infrastructure concerns such as database persistence and external integrations.

The system supports a wide array of funnel types—including lead generation, sales, and webinars—and features a visual page builder with over 25 element types. It integrates tightly with payment processors (Stripe) and analytics engines to track visitor journeys and conversion rates.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, specs/funnels/builder.yaml:5-20

Architecture and Domain Model

The module is structured into five sub-modules, each handling a specific aspect of the funnel lifecycle. The architecture follows a strict 4-layer DDD pattern: Domain, Application, Infrastructure, and Presentation.

Core Entities and Aggregate Roots

The system defines several primary entities that manage the state and business rules of the funnel system:

Entity	Description	Key Attributes
Funnel	The aggregate root for the funnel system. Manages steps, status, and versions.	id, account_id, name, funnel_type, status, version
FunnelStep	A value object representing a specific stage in a funnel (e.g., Opt-in, Upsell).	step_type, name, order, page_id, config
Page	The aggregate root for the landing page builder. Contains a tree of elements.	id, funnel_id, name, page_type, slug, elements
PageElement	A recursive value object defining UI components and their configurations.	element_type, config, styles, children

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, FUNNELS_QUICK_START.md

Entity Relationships

The following diagram illustrates the relationship between the account, funnels, steps, and pages within the domain.

The diagram shows that a Funnel contains multiple steps, each linked to a specific Page, which in turn is composed of various Page Elements.
Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, FUNNELS_QUICK_START.md

Funnel Lifecycle Management

The Funnel Builder sub-module (SPEC-FUN-001) manages the lifecycle of a funnel from creation to deployment. It ensures that steps are ordered sequentially and that naming remains unique within an account.

Key Functional Capabilities

• Cloning: Duplicating an existing funnel structure for rapid deployment.
• Version Control: Tracking snapshots of funnel configurations via the funnel_versions table.
• Step Reordering: Dynamically updating the sequence of steps (Opt-in -> Sales -> Thank You).
• Template Instantiation: Creating funnels from pre-defined system templates like blank, lead_capture, or sales_page.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, specs/funnels/builder.yaml:22-35

Funnel Creation Flow

This flow represents the standard initialization of a funnel, starting the entity in a DRAFT status.
Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, FUNNELS_QUICK_START.md

Page Builder and Visual Elements

The Page system (SPEC-FUN-002) allows for the visual construction of landing pages. Pages are composed of a tree-like structure of PageElements which support responsive design and SEO metadata.

Supported Element Categories

The builder supports 25 total element types categorized as follows:

• Basic: Headline, subheadline, text, button, divider, spacer.
• Media: Image, video, gif, image_gallery.
• Forms: Form, input_field, textarea, dropdown, checkbox_group.
• Advanced: Countdown timer, social proof, testimonial, pricing table.
• Layout: Columns, sections, containers, and rows.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, specs/funnels/builder.yaml:55-70

Page Persistence and Deployment

Pages utilize page_assets for S3-stored files and page_versions for history. The publishing process involves generating an HTML preview and deploying the page to a CDN (Cloudflare) with automatic SSL provisioning.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, specs/funnels/builder.yaml:145-160

API Interface

The Presentation layer provides a RESTful API for managing funnels and pages.

Core Funnel Endpoints

Method	Endpoint	Description
POST	/api/v1/funnels	Create a new funnel structure.
GET	/api/v1/funnels/{id}	Retrieve detailed funnel configuration and steps.
POST	/api/v1/funnels/{id}/clone	Create an exact replica of a funnel.
POST	/api/v1/funnels/{id}/steps	Add a new step (e.g., Upsell) to the funnel flow.
POST	/api/v1/funnels/{id}/steps/reorder	Update the sequential order of funnel steps.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, FUNNELS_QUICK_START.md

Core Page Endpoints

Method	Endpoint	Description
PATCH	/api/v1/pages/{id}	Update page elements or configuration.
POST	/api/v1/pages/{id}/publish	Transition page status to active and deploy to CDN.
GET	/api/v1/pages/{id}/preview	Generate a temporary HTML preview for mobile/desktop.
PATCH	/api/v1/pages/{id}/seo	Update meta tags and OpenGraph data.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, specs/funnels/builder.yaml:120-135

Database Schema and Persistence

The infrastructure layer utilizes PostgreSQL with SQLAlchemy for asynchronous data access. The schema is optimized with composite indexes (account_id + name) and partitioned tables for analytics.

Primary Tables

• funnels: Stores core funnel metadata.
• funnel_steps: Stores the sequence and type of steps in a funnel.
• pages: Stores the JSONB representation of the page element tree.
• page_versions: Stores snapshots for point-in-time recovery.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, FUNNELS_QUICK_START.md

# Example Funnel Aggregate usage from Domain Layer
# Sources: [FUNNELS_QUICK_START.md]
funnel = Funnel(
    account_id=uuid4(),
    name="Sales Funnel",
    funnel_type=FunnelType.SALES,
    status=FunnelStatus.DRAFT,
    created_by=user_id,
)

step1 = FunnelStep(
    step_type="page",
    name="Sales Page",
    page_id=page_id,
)

funnel.add_step(step1)
funnel.publish()

The Funnel & Page Management module provides a robust, scalable foundation for marketing automation. By leveraging DDD principles and a flexible element-based page builder, the system allows users to create complex, multi-step sales journeys while maintaining strict data isolation and performance through optimized database strategies and asynchronous processing.