> ## 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.

# ADR-001: Form Analytics Architecture

> The platform has two specifications for form analytics: 1. PF-09: Form Analytics & Usage Insights - Platform-level analytics (implemented) 2. FW-27: Form Analy…

**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

| 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?

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

## Related Documents

* [PF-09: Form Analytics & Usage Insights](https://github.com/Encore-OS/encoreos/blob/development/specs/pf/specs/PF-09-form-analytics.md)
* [FW-27: Form Analytics & Insights](https://github.com/Encore-OS/encoreos/blob/development/specs/fw/specs/FW-27-form-analytics-insights.md)
* [Forms Use Case Guide](/guides/use-cases/forms)