System Architecture Overview

Relevant source files

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

• plan.md
• README.md
• src/engine/optimizationLoop.ts
• src/engine/interpreter.ts
• src/engine/promptCompiler.ts
• src/engine/codeAnalyzer.ts
• src/engine/codeModifier.ts

Abee (SynthCrowd) is a synthetic user testing and website optimization platform. The system architecture is designed to transform a natural language description of an Ideal Customer Profile (ICP) into hundreds of autonomous AI browser agents that test a target website, identify friction points, and iteratively propose or apply code changes to improve conversion rates.

The platform operates through a multi-stage pipeline involving persona generation, parallel agent execution, and an automated optimization loop that modifies source code based on failure analysis.

Sources: plan.md:3-8, README.md:3-8

Core Pipeline Architecture

The system follows a 5-stage pipeline to process user inputs and generate actionable insights or code modifications.

The diagram shows the iterative flow from initial input through testing and analysis to code modification and rerunning.
Sources: plan.md:12-70, README.md:17-30

Key Architectural Components

1. Persona Engine

The Persona Engine converts abstract descriptions into structured data and eventually into high-fidelity system prompts for LLM agents.

• Interpreter (src/engine/interpreter.ts): Uses Claude to map natural language or website content to a PersonaConfig object containing 19 traits (e.g., tech_literacy, patience, trust_baseline).
• Population Generator (src/engine/population.ts): Uses Gaussian distribution (Box-Muller transform) to create $N$ diverse personas around the center-point config.
• Prompt Compiler (src/engine/promptCompiler.ts): Maps trait values to deterministic behavioral rules. For example, a tech_literacy < 0.2 triggers rules about not understanding hamburger menus.

Sources: README.md:32-110, src/engine/promptCompiler.ts:5-15

2. Execution & Streaming

The system executes agents in parallel and streams telemetry data for real-time monitoring and post-run analysis.

• Parallel Runner: Orchestrates batches of agents (typically 5-10) using the Browser Use SDK.
• Convex Integration: Streams real-time events (clicks, confusion, frustration, abandonment) to a Convex backend for dashboarding.
• Daytona Sandboxing: (Planned) Provides isolated environments for each agent to ensure no shared cookies or session state.

Sources: plan.md:30-41, README.md:144-165, src/engine/optimizationLoop.ts:161-190

3. Optimization Loop (src/engine/optimizationLoop.ts)

The differentiator of the platform is the "Fix" phase, which closes the loop by modifying the target application's code.

Component	Responsibility	Relevant Files
Code Analyzer	Analyzes failure narratives and proposes minimal, targeted code changes (HTML/CSS/JS) to fix friction.	src/engine/codeAnalyzer.ts
Code Modifier	Applies changes to the local filesystem, performs Git commits/reverts for safety, and verifies the site still loads.	src/engine/codeModifier.ts
Orchestrator	Manages the loop across iterations (max 5) until the conversion threshold (e.g., 75%) is met.	src/engine/optimizationLoop.ts

Sources: plan.md:104-123, src/engine/optimizationLoop.ts:133-288

Data Models

Persona Configuration Trait Categories

The PersonaConfig is the central data structure defining agent behavior.

Category	Traits
Demographics	age, gender, location, income_bracket, education
Digital Behavior	tech_literacy, patience, attention_span, device_preference
Domain Context	domain_familiarity, goal_clarity, purchase_intent, price_sensitivity
Behavioral	decision_style, jargon_tolerance, form_tolerance, trust_baseline

Sources: README.md:173-231, src/engine/interpreter.ts:14-36

Optimization Sequence

The following sequence describes the interactions during an optimization iteration where the system identifies a failure and applies a code fix.

Technical Implementation Details

• Failure Analysis: The CodeAnalyzer uses Claude-Sonnet-4 to group friction points and identify the code responsible. It requires the "original" string to be an exact verbatim copy-paste from the source code for replacement safety.
  • Sources: [src/engine/codeAnalyzer.ts:18-35](https://github.com/hrantvirabyan/YC2026/blob/HEAD/src/engine/codeAnalyzer.ts#L18-L35)
• Safety Mechanisms: The CodeModifier performs a git commit before every change and a health check (verifySiteLoads) after every change. If the site returns a non-200 status or malformed HTML, it immediately executes a git revert.
  • Sources: [src/engine/codeModifier.ts:34-58](https://github.com/hrantvirabyan/YC2026/blob/HEAD/src/engine/codeModifier.ts#L34-L58)
• Rule Selection: Rules in the PromptCompiler are selected based on the extremity of a trait (distance from 0.5). This ensures that a persona's most defining characteristics have the greatest impact on its browsing behavior.
  • Sources: [src/engine/promptCompiler.ts:360-375](https://github.com/hrantvirabyan/YC2026/blob/HEAD/src/engine/promptCompiler.ts#L360-L375)

Conclusion

The Abee architecture shifts user testing from a reactive report-only model to an active, iterative optimization platform. By combining high-fidelity LLM personas with a git-backed code modification engine, the system can automatically improve website conversion rates based on synthetic human feedback.

Sources: plan.md:10-11, README.md:233-247