website·Indexed 30 days ago
https://keak-docs-production.up.railway.app/Documentation for the Keak-Code Telemetry DB system architecture, covering the Variant Lifecycle State Machine, session database schema, code rendering, tracking implementation, and the end-to-end user journey from element interaction to experiment launch.
The Keak Code IDE provides developer-centric A/B testing integrated directly into the codebase. Features include:
The Keak Chrome Extension allows for no-code A/B testing. Key capabilities include:
KeaFab uses a three-phase AI pipeline to transform a selected UI component into a CRO-optimized variant. Unlike generic LLMs, it routes requests to specialized agents trained on conversion psychology and component-specific strategies (e.g., Hero sections vs. Pricing tables).
The Pipeline Phases:
The Keak dashboard acts as a proxy between the browser extension and the AI engine (KeaChrome). All extension calls are sent to ${BACKEND_URL}/... (which resolves to https://platform.keak.com/api in production). The dashboard validates authentication and billing before proxying requests to KeaChrome's internal adapters.
Key endpoints include:
POST /api/v2/page-agent/generate and POST /api/v2/page-agent/refine. These proxy to PageAgentAdapter, where the server drives a Playwright page for screenshots, allowing the extension tab to be closed.POST /api/v2/variants/generate and POST /api/v2/variants/refine. Used when isBetaModeEnabled() is false; these proxy to ClientInputAdapter and require the tab to remain open for screenshot uploads.POST /api/tests (single) or /api/tests/group (batch) to persist test variations.Keak-Code uses a 3-tier state architecture to ensure data durability and prevent state loss during app restarts:
localStorage..keak/history/history.json.Key Features:
KeakId is a stable, human-readable identifier injected into source code as a data-keak-id attribute. It ensures tracking survives refactors, provides a key for chat history per element, and allows for file-based persistence via grep. If a keakId is accidentally removed, the system automatically re-injects it upon the next element selection.data-keak-id), variant authoring (Generate vs Refine), and in-place DOM previews using local Zustand and localStorage stores.The Keak MCP server is designed as a thin client where every tool maps to a dashboard endpoint. It uses a layered architecture to ensure extensibility:
index.ts): Handles stdio transport.server.ts): Builds the McpServer, injects context, and registers tools.keak-client): The sole location for fetch calls; handles typed API methods and unwraps { data } envelopes.context/): Manages per-session in-memory state (e.g., recommended goals, client_session_id, and CRO reports) to avoid passing large payloads back and forth to the LLM.lib/): Contains tool definitions, presentation formatting, and an async-job poller.Async Job Handling: Because CRO reports can take minutes and MCP clients have a ~60s timeout, create_cro_report starts a job and polls for ~45s. The model must then use get_cro_report to advance and check the job status.
// Example: Transitioning from Control to Variant Preview
// 1. Read disk (captures control edits!)
const currentCode = readDisk();
// 2. Capture to control snapshot
snapshot.originalCode = currentCode;
// 3. Write variant to disk
writeDisk(variantCode);
// 4. Update flag
snapshot.activePreview = true;The telemetry system tracks the entire variant generation workflow (Session Start → Chat Start → Generation Start → Generation Complete → Variant Preview → Variant Accept), including feedback and edits.
Data Flow:
use-cro-telemetry and useKeafabGenerator send data to telemetryService.ts./app/api/telemetry/*).TELEMETRY_SUPABASE_URL), which is isolated from the main Dashboard database for performance and scalability.