EverConvert Documentation

Table of contents

Technology stack

• Frontend: React + Vite + TypeScript + Tailwind CSS with a tokenized design system and shadcn UI components.
• State & data: React Query for caching/fetching; lightweight local state with hooks.
• Routing: react-router-dom with SPA-style SEO enhancements (title, meta, canonical).
• Backend: Supabase for Postgres, Row Level Security, Edge Functions, and Auth.
• Charts/visuals: Recharts; Icons via lucide-react.

App structure

Key directories and responsibilities:

• src/pages: Top-level routes (Index, Monitor, Documentation). Each page sets SEO and renders feature modules.
• src/components: Feature modules like TestBuilder, TestMonitor, analytics views, trackers, and UI primitives.
• src/hooks: Reusable hooks (e.g., useAuth) to encapsulate cross-cutting concerns.
• supabase/functions: Edge functions for generation, optimization, and tracking.

Core user flows

1. Create Test (Index page): Build an A/B test targeting a URL and element selector. Initial variants can be generated, and the test moves to active when started.
2. Optimize (Edge): The optimize-experience function selects a variant per visitor (Thompson Sampling + context multipliers) and tracks impressions.
3. Monitor (Monitor page): TestMonitor and detailed analytics aggregate interactions to show impressions, conversions, and winner candidates with filters.

Database & security (RLS)

The schema centers on sites, tests, variants, interactions, and test_results. RLS ensures users only see data from their own sites.

• interactions: insertable by the tracker; selectable for site owners; stores impressions/conversions and visitor features.
• tests/variants: describe experiments and content; views restricted to owner where applicable.
• test_results: aggregated stats for performance and significance.

Tracking lifecycle

1. A page includes the tracker script which assigns a stable visitorId and detects context (device, country, referrer).
2. The page calls optimize-experience with siteId, visitorId, and features; it returns the variant to render and an impression is recorded.
3. Conversions are posted to track-conversion or recorded via track-interaction, joining with the active test/variant.

Edge functions overview

• optimize-experience: Chooses variants via Thompson Sampling and context; logs impressions.
• headline-iteration-engine: Generates/archives variants by segment; can promote winners under uplift rules.
• track-*: Ingests interactions and errors for observability and attribution.

Monitoring & analytics

The Monitor view aggregates recent interactions with filters (device/source/country/visitor type) and highlights winning variants by conversion rate.

Realtime subscriptions can be added to update stats instantly as new events arrive. Export to CSV is supported in the monitor to facilitate offline analysis.

Operations & SEO

• SEO: Each page sets title, description, and a canonical tag; images use descriptive alt text when present.
• Security: Sensitive tables use RLS with owner-only reads; inserts for trackers are constrained by policy.
• Performance: Tailwind design tokens; batched queries; optional indexes on interactions for scale.
• Navigation: Direct links to Create Test and Monitor.