Encore OS — Documentation

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

Context

The platform has two specifications for form analytics:

PF-09: Form Analytics & Usage Insights - Platform-level analytics (implemented)
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

Capability	Owner	Spec
Event tracking infrastructure	Platform Foundation	PF-09
Basic completion metrics	Platform Foundation	PF-09
Field interaction stats	Platform Foundation	PF-09
Analytics dashboard (basic)	Platform Foundation	PF-09
A/B Testing	Forms & Workflow	FW-27
Drop-off funnel visualization	Forms & Workflow	FW-27
Multi-page analytics	Forms & Workflow	FW-27
Advanced segmentation	Forms & Workflow	FW-27
Performance percentiles	Forms & Workflow	FW-27

Rationale

Why Two Specs?

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

Why Not Merge?

Different Audiences: PF-09 serves platform admins. FW-27 serves form designers and optimization teams.
Different Complexity: PF-09 is straightforward aggregation. FW-27 includes statistical significance testing, traffic splitting, etc.
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

Organization Document Templates - Architecture Document ADR-002: CL-PM Cross-Core Foreign Keys

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

ADR-001: Form Analytics Architecture

Context

Decision

Architecture

Ownership

Rationale

Why Two Specs?

Why Not Merge?

Consequences

Positive

Negative

Mitigations

​Context

​Decision

​Architecture

​Ownership

​Rationale

​Why Two Specs?

​Why Not Merge?

​Consequences

​Positive

​Negative

​Mitigations

​Related Documents

Context

Decision

Architecture

Ownership

Rationale

Why Two Specs?

Why Not Merge?

Consequences

Positive

Negative

Mitigations

Related Documents