How jlin3/runthru works
Project type and purpose
• RunThru is a full-stack web application whose goal is to generate AI-driven end-to-end QA screen recordings. It interprets natural-language test scenarios, runs them in an automated browser, records video, generates narration, composes the final demo, and serves real-time updates to users.
Key architectural components (derived from file tree & README)
a. Frontend (client/)
• React + Vite + TypeScript UI
• Pages & components for configuration form, execution status, history, and live progress
• WebSocket client for real-time updates
• Query client (React-Query) for REST API calls
b. Backend API (server/)
• Express.js + TypeScript HTTP server
• Routes (server/routes.ts) exposing REST endpoints: generate-steps, create session, start, download
• WebSocket (server/index.ts or server/eventBus.ts) for pushing progress events
c. Agent Orchestration (packages/agent)
• LLM-driven “agents” (screenRecordAgent, metadataAgent, testScriptAgent, voiceoverAgent, etc.)
• Tooling modules: generateMetadata, planTest, runBrowser, mergeVideo, sendToStakeholder
d. Services (server/services)
• openaiService (GPT-4o + TTS calls)
• playwrightService (browser automation & screen recording)
• videoService (FFmpeg composition)
• storage services: gcpStorageService, supabaseService, unifiedStorageService
• pipelineAgentService (coordinates the multi-step flow)
• realtimeVoiceService (WebSocket audio stream)
e. Data layer
• Supabase (PostgreSQL) for session metadata & history (scripts/setup-supabase.js)
• File storage on GCP buckets or local uploads/videos
f. External systems
• OpenAI API (chat + text-to-speech)
• Playwright (headless browser)
• FFmpeg CLI
• Supabase / Postgres
• GCP Storage
Relationships & data flows
• User → Frontend UI
• Frontend → Backend REST API (HTTP POST /api/recordings/…)
• Backend → Agent Orchestrator (invoke packages/agent)
• Agent Orchestrator → Services in series:
1. openaiService.generateTestSteps
2. playwrightService.runBrowser (with screen capture)
3. openaiService.generateVoiceover
4. videoService.mergeVideo + avatar overlay
• Services → Storage (upload intermediate files & final video via GCP/Supabase)
• Backend → Frontend via WebSocket events (Progress updates, status changes)
• Frontend → Supabase / History API for recording history retrieval
• Frontend → Download endpoint for final video
Architectural patterns & principles
• Separation of concerns: UI (client) vs API (server) vs orchestration (packages/agent) vs services
• Modular “agent” design: each LLM task or tooling step is an independent agent module
• Pipeline pattern: sequential data processing stages
• Event-driven updates via WebSocket / eventBus
• Monorepo structure with pnpm workspaces for shared types (shared/schema.ts)
Final checklist
• Layers & components fully decoupled and labeled
• Enough granularity to see frontend pages, backend services, agent modules, and external integrations