Report Generator

Relevant source files

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

• src/engine/reportGenerator.ts
• src/engine/optimizationLoop.ts
• plan.md
• README.md
• src/test-demo-site.ts
• src/test-full-pipeline.ts

The Report Generator is a critical component of the SynthCrowd (Abee) platform, responsible for synthesizing raw browsing session data into actionable UX insights. It processes events generated by synthetic AI personas—capturing their steps, evaluations, and emotional states (confusion or frustration)—to produce a structured friction report. Sources: README.md:16-25, src/engine/reportGenerator.ts:9-12

This module utilizes the Anthropic Claude LLM (specifically claude-sonnet-4-20250514) to analyze sequences of events and output JSON-formatted findings. These findings include ranked friction points, per-persona narratives, and specific recommendations for website improvement. Sources: src/engine/reportGenerator.ts:108-112, README.md:144-152

System Architecture and Data Flow

The Report Generator operates as Phase 3 of the overall project pipeline. It acts on data collected during Phase 2 (Test), where parallel runners execute agents across a target site. Sources: plan.md:37-48

The diagram above illustrates how the Report Generator retrieves events from a persistent sink, processes them via an LLM, and stores the structured results for either display or further code optimization. Sources: src/engine/reportGenerator.ts:94-150, src/engine/optimizationLoop.ts:168-185

Key Components

Component	Description	Source File
generateReport	The main asynchronous function that orchestrates event fetching, LLM prompting, and result storage.	src/engine/reportGenerator.ts:94
buildReportPrompt	Formats persona identities and step-by-step event logs into a string for LLM analysis.	src/engine/reportGenerator.ts:68
REPORT_SYSTEM_PROMPT	A strict system prompt defining the UX analyst role and the required JSON output schema.	src/engine/reportGenerator.ts:9-39
ConvexEventSink	Interface used to fetch raw events from the database and store the final results.	src/engine/reportGenerator.ts:95

Data Processing Logic

The generator processes PersonaRunData, which aggregates a persona's identity (age, tech literacy, decision style) with their chronological EventData. Sources: src/engine/reportGenerator.ts:54-66

Event Aggregation

The system maps events to specific persona indices to reconstruct the user journey. Each step includes:

• Page URL: Where the action occurred.
• Next Goal: What the agent was trying to achieve.
• Evaluation: The agent's internal monologue about the current state.
• Flags: Boolean indicators for is_confused or is_frustrated.
  Sources: src/engine/reportGenerator.ts:42-51, src/engine/reportGenerator.ts:105-115

LLM Synthesis and Output Schema

The generator instructs the LLM to produce a JSON object with the following structure:

{
  "friction_points": [
    {
      "description": "string",
      "page_url": "string",
      "personas_affected": "number",
      "severity": "low|medium|high|critical"
    }
  ],
  "per_persona_summaries": [
    {
      "persona_index": "number",
      "outcome": "converted|abandoned",
      "narrative": "3rd person narrative",
      "pages_visited": "number",
      "abandonment_point": "URL or null",
      "confusion_points": ["string"]
    }
  ],
  "recommendations": ["string"]
}

Sources: src/engine/reportGenerator.ts:16-36

Integration with Optimization Loop

In the "Fix" phase of the platform, the Report Generator's output is consumed by the Code Analysis Agent. This agent reads the failure narratives and friction points to propose specific code modifications. Sources: plan.md:50-55, src/engine/optimizationLoop.ts:213-231

This sequence shows the Report Generator's role in providing the analytical foundation for the automated code improvement cycle. Sources: src/engine/optimizationLoop.ts:168-235

Usage in Testing

The report output is used across various test suites to validate persona fidelity and conversion rates. In the test-demo-site script, the report is printed to the console to show friction points and persona narratives. Sources: src/test-demo-site.ts:101-125, src/test-full-pipeline.ts:32-58

Result Storage

Final reports are persisted to the Convex results table, including metadata such as:

• Conversion Rate: Total successful conversions / total agents.
• Persona Snapshots: Demographic data of the personas used in the run.
• Friction Severity: Ranking points from "low" to "critical".
  Sources: src/engine/reportGenerator.ts:143-176, README.md:255-263

Conclusion

The Report Generator serves as the "Analysis" engine of SynthCrowd. By transforming discrete browser events into high-level UX insights, it enables the platform to not only identify where users struggle but also provide the necessary context for automated code fixes and manual optimizations. Sources: plan.md:41-45, README.md:21-25