Orders & Funnel Analytics

Relevant source files

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

• FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md
• FUNNELS_QUICK_START.md
• specs/funnels/builder.yaml
• DDD_IMPLEMENTATION_REPORT_SPEC_WFL_009.md
• SPEC-WFL-007-EXECUTIVE-SUMMARY.md

Introduction

The Orders & Funnel Analytics system is a critical component of the Funnels Module, designed to handle the end-to-end e-commerce lifecycle and performance tracking of marketing funnels. This system manages complex payment flows, including order bumps and post-purchase upsells, while simultaneously capturing granular visitor data to provide actionable insights into conversion rates and drop-off points.

The scope of this module includes secure payment processing via Stripe, management of multi-step order aggregates, and a time-series analytics engine that supports A/B testing and real-time monitoring. By integrating order data with visitor behavior, the platform allows for comprehensive ROI analysis and optimization of the sales journey.
Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:14-22, FUNNELS_QUICK_START.md:3-8

Order Management System (SPEC-FUN-003)

The Order Management system follows Domain-Driven Design (DDD) principles, centering on the Order aggregate root. It is responsible for orchestrating payments, managing line items, and handling post-purchase adjustments like upsells or refunds.

Core Architecture and Components

The system utilizes a 4-layer DDD architecture to separate business logic from infrastructure concerns:

• Domain Layer: Contains the Order aggregate, OrderItem value objects, and entities for OrderBump, UpsellDownsell, and Refund.
• Application Layer: Implements 12 use cases, including payment intent creation and order processing.
• Infrastructure Layer: Manages SQLAlchemy models for 5 tables and integrates with the Stripe API.
• Presentation Layer: Exposes 12 FastAPI endpoints for frontend interaction.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:188-212, FUNNELS_QUICK_START.md:76-92

Order Payment Flow

The payment process is a multi-step sequence designed to ensure security and support one-click upsells.

Data Structure: Order Aggregate

Field	Type	Description
id	UUID	Primary key for the order
account_id	UUID	Multi-tenant identifier
order_number	String	Unique human-readable identifier
customer	Object	Nested object with email, name, and address
items	Array	List of OrderItem value objects
total_cents	Integer	Total value in minor currency units
status	Enum	draft, pending, paid, completed, cancelled

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:195-202, FUNNELS_QUICK_START.md:213-218

Funnel Analytics (SPEC-FUN-004)

The Analytics system provides performance tracking and conversion optimization features. It utilizes time-series data partitioning and materialized views to maintain high performance even with large datasets.

Analytics Tracking Logic

The system tracks four primary event types to reconstruct the visitor journey:

1. page_view: Captured when a visitor lands on a funnel page.
2. step_entry: Captured when a visitor enters a specific step.
3. step_exit: Captured when a visitor leaves a step, noting the outcome.
4. conversion: Captured upon goal completion (e.g., a purchase or form submission).

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:243-255, FUNNELS_QUICK_START.md:111-125

Funnel Performance Architecture

A/B Testing and Optimization

The analytics system supports A/B testing via the ABTest and ABTestVariant entities. It calculates statistical significance to determine "winning" variants based on traffic splits.

• Materialized Views: The funnel_step_stats view refreshes every 5 minutes to provide near real-time dashboards.
• Drop-off Analysis: Identifies steps with high exit rates and provides suggestions for optimization.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:245-265, specs/funnels/builder.yaml:126-135

Goal Tracking and Conversions

Goal tracking allows users to define specific success criteria within a funnel, such as form submissions or reaching a pipeline stage.

Goal Types

The system supports 5 primary goal types for conversion tracking:

Goal Type	Event Trigger	Description
TAG_ADDED	CRM Event	Contact receives a specific tag
PURCHASE_MADE	Payment Event	Order is marked as paid
APPOINTMENT_BOOKED	Calendar Event	Booking is confirmed
FORM_SUBMITTED	Form Event	User submits a funnel form
PIPELINE_STAGE	CRM Event	Deal moves to a target stage

Sources: SPEC-WFL-007-EXECUTIVE-SUMMARY.md:78-86, specs/funnels/builder.yaml:69-78

Database Schema Reference

The Orders and Analytics modules utilize 9 specialized tables.

Order Tables

• orders: Main order records including status and payment info.
• order_items: Line items associated with an order.
• order_bumps: Pre-purchase offers accepted during checkout.
• order_upsells: Post-purchase offers processed as separate transactions.
• refunds: Records of partial or full amount reversals.

Analytics Tables

• analytics_events: Time-series table partitioned by month for high-volume storage.
• funnel_step_stats: Materialized view for aggregated step performance.
• ab_tests: Configuration and status of A/B experiments.
• ab_test_variants: Specific versions (Control vs. Variant) for testing.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:144-150, FUNNELS_QUICK_START.md:208-225

API Reference

Key endpoints for managing orders and retrieving analytics data.

Endpoint	Method	Description
/api/v1/orders/payment-intent	POST	Creates a Stripe PaymentIntent for the frontend.
/api/v1/orders	POST	Persists an order after payment verification.
/api/v1/orders/analytics	GET	Returns sales trends and revenue metrics.
/api/v1/analytics/track	POST	Records a visitor event (view, click, etc.).
/api/v1/analytics/funnels/{id}/overview	GET	Aggregated funnel performance summary.
/api/v1/analytics/funnels/{id}/dropoffs	GET	Detailed breakdown of visitor exits per step.

Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:220-227, FUNNELS_QUICK_START.md:104-128

Conclusion

The Orders & Funnel Analytics system provides a robust framework for managing revenue and measuring performance. By leveraging a partitioned database schema for analytics and a clean DDD structure for orders, the platform ensures both financial accuracy and system scalability. This integration of data enables users to not only process sales but also deeply understand visitor behavior through automated A/B testing and drop-off analysis.
Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md:374-385, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_009.md:142-150