Convex Database Schema

Relevant source files

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

• convex/schema.ts
• convex/_generated/dataModel.d.ts
• convex/_generated/server.d.ts
• README.md
• plan.md
• src/engine/reportGenerator.ts

The Convex Database Schema serves as the real-time persistence layer for Abee, a synthetic crowd-testing platform. It is designed to manage the lifecycle of test runs, store the configurations of synthetic personas, stream real-time events from autonomous browser agents, and aggregate final analysis results. The schema is defined using Convex's type-safe defineSchema and defineTable utilities, ensuring consistency between the backend data and the application's TypeScript logic.

The database architecture is structured around four primary tables that track the progress of a test from initial user input to final conversion metrics and improvement suggestions. This real-time infrastructure allows the frontend to subscribe to updates as agents navigate target websites, providing a live dashboard of synthetic user behavior.

Sources: convex/schema.ts:1-155, README.md:214-239, plan.md:73-77

Entity Relationship Overview

The schema establishes clear relationships between test runs, the personas generated for those runs, the granular events produced during execution, and the final aggregated results.

Data Models

Runs Table

The runs table tracks the metadata and lifecycle of a specific testing session. It captures the target URL, the conversion goal (CTA), and the initial parameters used to generate the synthetic population.

Field	Type	Description
url	string	The target website URL being tested.
goal	string	The conversion goal (e.g., "Complete a purchase").
user_input	string	The raw natural language ICP description.
status	enum	Lifecycle: configuring, running, completed, failed.
conversion_rate	optional number	The final percentage of agents that met the goal.

Sources: convex/schema.ts:60-76, README.md:218-220

Personas Table

The personas table stores the 19-trait configuration for every synthetic user in a run. This includes demographics, digital behavior, and deterministic rules that guide agent navigation.

// Shared validator used for individual persona storage
const personaConfigValidator = {
  age: v.number(),
  tech_literacy: v.number(),
  patience: v.number(),
  decision_style: v.union(v.literal("impulsive"), v.literal("methodical"), v.literal("cautious"), v.literal("research_heavy")),
  behavioral_rules: v.array(v.string()),
  identity_prompt: v.string(),
  // ... (14 other traits)
};

Sources: convex/schema.ts:4-44, README.md:222-224

Agent Events Table

This table acts as a high-frequency event stream. Every step taken by a browser agent (e.g., clicking, scrolling, or encountering confusion) is recorded here. It includes an index by_run_persona to allow the UI to filter live streams for specific agents.

Field	Type	Description
run_id	Id<"runs">	Reference to the parent run.
persona_index	number	Identifier for the specific persona in the population.
is_confused	boolean	Flag indicating if the agent's LLM reported confusion.
status	enum	Current state: navigating, confused, converted, abandoned.

Sources: convex/schema.ts:78-103, README.md:226-231

Results Table

The results table stores the final synthesis of a run, typically generated by the reportGenerator module. It aggregates individual event streams into high-level friction points and human-readable narratives.

• Friction Points: An array of objects describing where agents got stuck, including severity and URL.
• Per-Persona Summaries: A snapshot of the persona's journey, including the outcome (converted/abandoned) and a narrative explaining their experience.

Sources: convex/schema.ts:105-154, src/engine/reportGenerator.ts:145-188

Implementation Details

The schema is integrated into the project through generated TypeScript utilities that provide full type safety for database operations.

Indexing Strategy

To ensure performance during real-time streaming and post-run analysis, the schema defines specific indexes:

1. personas.by_run: Optimized for retrieving the full population for a test.
2. agent_events.by_run: Used for global progress tracking.
3. agent_events.by_run_persona: Enables the "Live Agent Analytics" dashboard to follow a single persona's journey.
4. results.by_run: Fast lookup for the final report.

Sources: convex/schema.ts:57, 102-103, 154

Summary

The Convex Database Schema is the backbone of the Abee platform's data flow. By separating granular, high-frequency events (agent_events) from static configurations (personas) and final summaries (results), it supports both real-time monitoring and long-term storage of synthetic user testing sessions.

Sources: README.md:214-239, plan.md:73-77