MongoDB Persona Persistence

Relevant source files

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

• src/lib/mongoClient.ts
• plan.md
• src/engine/optimizationLoop.ts
• src/test-smoke.ts
• src/test-demo-site.ts

MongoDB Persona Persistence is a core infrastructure component of the SynthCrowd platform designed to provide long-term storage and snapshotting of synthetic user testing data. Its primary purpose is to ensure that generated personas and their historical performance data are preserved across multiple iterations of the website optimization loop. By persisting these records, the system can reuse specific persona configurations in subsequent tests, allowing for controlled experiments where only the website code changes while the "audience" remains constant.

This system functions as the "memory" of the optimization pipeline, capturing full run snapshots including agent configurations, interaction events, conversion reports, and fidelity scores. This is critical for the "Rerun" phase of the project, where the same personas are pulled from MongoDB to verify if code changes successfully reduced friction without breaking existing successful paths.

Sources: plan.md:16-30, plan.md:95-98, src/lib/mongoClient.ts:1-10

Architecture and Data Flow

The persistence layer is implemented via a dedicated client that interacts with a MongoDB database named synthcrowd. It utilizes two primary collections: personas for storing reusable user profiles and runs for logging the results of specific testing iterations.

Core Components

• MongoDB Client: A singleton-pattern connection manager that initializes the database connection using the MONGODB_URI environment variable.
• Persona Storage: Logic for upserting persona arrays linked to a session_id.
• Run Persistence: Logic for inserting immutable records of a complete testing cycle, including the configuration, events, and outcome metrics.

Sources: src/lib/mongoClient.ts:7-30

Persistence Flow

The following diagram illustrates how the persistence layer interacts with the optimization loop during a typical testing cycle.

The flow ensures that personas are stored immediately after generation and retrieved in subsequent iterations (2+) to maintain consistency.
Sources: src/engine/optimizationLoop.ts:145-165, src/engine/optimizationLoop.ts:219-236

Data Models and Schemas

The system persists data in two distinct structures within the MongoDB collections.

Run Persistence Schema

The runs collection stores a comprehensive snapshot of a specific testing iteration.

Field	Type	Description
session_id	string	UUID linking multiple iterations to one project session
run_id	string	Unique identifier for the specific execution
iteration	number	The sequence number of the optimization loop
config	Object	Includes icp_input, target_url, goal, and population_size
personas	PersonaConfig[]	Array of the specific persona configurations used
events	unknown[]	Step-by-step browser agent interaction logs
report	unknown	The synthesized friction and recommendation report
conversion_rate	number	Percentage of personas that reached the goal
created_at	Date	Timestamp of record creation

Sources: src/lib/mongoClient.ts:32-55, src/engine/optimizationLoop.ts:219-236

Persona Session Schema

The personas collection uses an "upsert" strategy to maintain the master list of synthetic users for a session.

Field	Type	Description
session_id	string	Primary key for project-wide persona retrieval
personas	PersonaConfig[]	The raw traits and behavioral rules for the population
updated_at	Date	Last time the session's population was modified

Sources: src/lib/mongoClient.ts:60-78

Implementation Details

Database Connection Management

The persistence layer uses a lazy-initialization pattern to manage the MongoClient. It requires a MONGODB_URI to be present in the environment; otherwise, it throws an error during the first database access attempt.

// src/lib/mongoClient.ts:10-23
async function getDb(): Promise<Db> {
  if (db) return db;

  const uri = process.env.MONGODB_URI;
  if (!uri) throw new Error("MONGODB_URI environment variable is required");

  client = new MongoClient(uri);
  await client.connect();
  db = client.db("synthcrowd");
  console.log("[mongo] Connected to MongoDB");
  return db;
}

Sources: src/lib/mongoClient.ts:10-23

Sequence Diagram: Persona Retrieval

This diagram shows how the OptimizationLoop interacts with MongoDB to ensure persona consistency across iterations.

Integration in Testing

The persistence system is verified through smoke tests and demo site analysis scripts. These scripts validate that connection strings are respected and that data is successfully committed to the cloud database after agent runs.

• Smoke Test: Verifies storePersonas and persistRun functions within a single-agent cycle.
• Demo Site Analysis: Uses persistence to track conversion rates across different personas in a read-only analysis.

Sources: src/test-smoke.ts:64-73, src/test-smoke.ts:108-132, src/test-demo-site.ts:74-80

Summary

MongoDB Persona Persistence provides the critical state management required for the SynthCrowd optimization loop. By decoupling persona generation from execution and providing a persistent store for results, it enables the platform to perform meaningful A/B style testing where code changes are the only variable. The system ensures that every interaction, from raw persona traits to final conversion reports, is captured with timestamped accuracy.

Sources: plan.md:95-98, src/lib/mongoClient.ts:54-55