Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Status: Accepted
Date: 2025-12-05
Decision Makers: Platform Architecture Team

​
Context

The platform has two specifications for form analytics:
  1. PF-09: Form Analytics & Usage Insights - Platform-level analytics (implemented)
  2. FW-27: Form Analytics & Insights - Advanced form analytics (spec complete)
There was potential confusion about whether these overlap or replace each other.

​
Decision

FW-27 EXTENDS PF-09, not replaces it.

​
Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Form Analytics Architecture                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   PF-09 (Platform Layer)                     │ │
│  │  ✅ IMPLEMENTED                                              │ │
│  │                                                               │ │
│  │  • pf_form_analytics_events (raw event tracking)             │ │
│  │  • pf_form_completion_metrics (aggregated metrics)           │ │
│  │  • pf_field_interaction_stats (field-level stats)            │ │
│  │  • log_form_analytics_event() function                       │ │
│  │  • aggregate-form-analytics edge function                    │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                              │                                    │
│                              │ extends                            │
│                              ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   FW-27 (Advanced Layer)                     │ │
│  │  📋 SPEC COMPLETE                                            │ │
│  │                                                               │ │
│  │  • fw_form_ab_tests (A/B test definitions)                   │ │
│  │  • fw_form_ab_results (test results & statistics)            │ │
│  │  • fw_form_analytics (extended aggregations)                 │ │
│  │  • fw_form_field_analytics (drop-off funnel data)            │ │
│  │  • fw_form_page_analytics (multi-page analytics)             │ │
│  │  • A/B test UI components                                    │ │
│  │  • Advanced visualization dashboards                         │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

​
Ownership

CapabilityOwnerSpec
Event tracking infrastructurePlatform FoundationPF-09
Basic completion metricsPlatform FoundationPF-09
Field interaction statsPlatform FoundationPF-09
Analytics dashboard (basic)Platform FoundationPF-09
A/B TestingForms & WorkflowFW-27
Drop-off funnel visualizationForms & WorkflowFW-27
Multi-page analyticsForms & WorkflowFW-27
Advanced segmentationForms & WorkflowFW-27
Performance percentilesForms & WorkflowFW-27

​
Rationale

​
Why Two Specs?

  1. Platform vs. Domain Ownership: PF-09 provides infrastructure that ANY module can use. FW-27 provides Forms-specific advanced features.
  2. Implementation Timeline: PF-09 can be implemented first as foundation. FW-27 is additive and optional.
  3. Code Location: PF-09 code lives in src/platform/analytics/. FW-27 code lives in src/cores/fw/components/analytics/.

​
Why Not Merge?

  1. Different Audiences: PF-09 serves platform admins. FW-27 serves form designers and optimization teams.
  2. Different Complexity: PF-09 is straightforward aggregation. FW-27 includes statistical significance testing, traffic splitting, etc.
  3. Optional Adoption: Organizations can use PF-09 without needing FW-27’s A/B testing complexity.

​
Consequences

​
Positive

  • Clear ownership boundaries
  • Incremental implementation path
  • Reusable analytics infrastructure
  • Forms team can innovate without platform changes

​
Negative

  • Two tables for form analytics (some redundancy)
  • Need to document relationship clearly
  • FW-27 depends on PF-09 being implemented first

​
Mitigations

  • FW-27 spec updated with explicit PF-09 relationship section
  • This ADR documents the decision
  • Cross-references added to both specs