Customizing the Demo Site

Relevant source files

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

• src/engine/codeAnalyzer.ts
• src/engine/codeModifier.ts
• src/engine/optimizationLoop.ts
• src/test-demo-site.ts
• plan.md
• demo-website/package.json
• demo-website/src/pages/FAQ.tsx
• demo-website/src/components/Footer.tsx

Customizing the Demo Site within the SynthCrowd platform involves a closed-loop system where synthetic user behavior directly informs automated or semi-automated code modifications. The primary goal is to reduce "friction points" identified during AI agent simulations by modifying the site's source code (HTML, CSS, JS/TSX) to improve conversion rates.

The customization process is driven by the Optimization Loop, which orchestrates failure analysis, code proposal generation, and the safe application of changes using Git-backed rollbacks. This ensures that the demo site evolves based on empirical agent data rather than subjective design choices.

Sources: plan.md:5-15, src/engine/optimizationLoop.ts:133-228

Architecture of the Customization Pipeline

The system uses a multi-stage pipeline to transform agent failure data into localized code changes. The process is designed to be conservative, prioritizing minimal targeted fixes over large-scale redesigns.

The diagram shows the transition from raw failure data to a verified, committed code change on the demo site.
Sources: plan.md:38-70, src/engine/codeModifier.ts:47-105

Code Analysis and Proposal

The codeAnalyzer identifies specific friction points (e.g., confusing copy, difficult forms, or missing trust signals) and correlates them with the site's source code. It targets files like FAQ.tsx or Footer.tsx to resolve issues such as unclear navigation or lack of company info.

The analyzer follows strict rules:

• Changes must target exactly one friction point.
• Proposals are limited to copy, styling, layout, and form structure.
• No new JavaScript dependencies or framework restructurings are allowed.

Sources: src/engine/codeAnalyzer.ts:16-36, demo-website/src/components/Footer.tsx

Key Components and Data Structures

Proposed Change Schema

The ProposedChange interface defines the structure for any modification intended for the demo site. A critical requirement is that the original field must be an exact, whitespace-sensitive substring of the existing code.

Field	Type	Description
file	string	The relative path to the file within the demo site (e.g., src/pages/FAQ.tsx).
description	string	A short summary of the intended modification.
original	string	The exact verbatim code block to be replaced.
replacement	string	The new code content to be injected.
reasoning	string	Technical justification for how this fix addresses agent friction.
targetFriction	string	The specific friction point identified in the simulation report.

Sources: src/engine/codeAnalyzer.ts:6-14, src/engine/codeAnalyzer.ts:31-34

Optimization Loop Configuration

The OptimizationOptions structure governs how the customization process iterates.

export interface OptimizationOptions {
  sitePath: string;      // Local path to the demo-website
  siteUrl: string;       // URL for live verification
  threshold: number;     // Target conversion rate (e.g., 0.75)
  maxIterations: number; // Max loop cycles (default 5)
  autoMode: boolean;     // If true, skips the User Approval Gate
}

Sources: src/engine/optimizationLoop.ts:24-40, plan.md:73-83

Safety and Verification Mechanisms

To prevent breaking the demo site during customization, the codeModifier implements a strict "Commit-Apply-Verify" pattern.

1. Git Integration: Before any change, the system performs a git commit. If a change breaks the site, it executes git checkout -- . to restore the last known good state.
2. Site Verification: The verifySiteLoads function checks if the site returns a 200 status and contains valid HTML markers (like </html> or root div).
3. String Validation: The modifier ensures the original string still exists in the file before attempting a replacement to avoid conflicts with previous iterations.

Sources: src/engine/codeModifier.ts:13-33, src/engine/codeModifier.ts:58-85

Supported Technologies

The demo site is built using a modern stack that the optimization agents are configured to interpret and modify.

• Framework: React with Vite
• Styling: Tailwind CSS and shadcn/ui
• Language: TypeScript
• Components: Radix UI primitives (Accordion, Dialog, etc.)

Sources: demo-website/package.json:44-88, demo-website/src/pages/FAQ.tsx:22-30

Summary

Customizing the demo site is an automated evolution process. By treating the website source code as a mutable target for a UX-focused LLM, the system can systematically eliminate conversion barriers. The combination of Gaussian population testing and Git-backed code modification allows the site to reach a specific conversion threshold through iterative refinement.

Sources: plan.md:5-15, src/engine/optimizationLoop.ts:228-245