# jlin3/runthru architecture

> Architecture diagram of the GitHub repository jlin3/runthru, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlin3/runthru
- Repository: https://github.com/jlin3/runthru

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        UI["React UI<br/>(Vite, TS)"]:::frontend
        ConfigForm["ConfigurationForm"]:::frontend
        ExecStatus["ExecutionStatus"]:::frontend
        History["RecordingHistory"]:::frontend
        QueryClient["queryClient"]:::frontend
        Config["config"]:::frontend
        UI --> ConfigForm
        UI --> ExecStatus
        UI --> History
        UI --> QueryClient
        UI --> Config
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["Express API<br/>(REST & WS)"]:::backend
        Routes["routes.ts"]:::backend
        EventBus["eventBus.ts"]:::backend
        API --> Routes
        API --> EventBus
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Orchestrator["Agent Orchestrator"]:::orchestrator
        ScreenAgent["screenRecordAgent"]:::orchestrator
        MetaAgent["metadataAgent"]:::orchestrator
        TestAgent["testScriptAgent"]:::orchestrator
        VoiceAgent["voiceoverAgent"]:::orchestrator
        DemoAgent["demoVideoAgent"]:::orchestrator
        StakeholderAgent["stakeholderAgent"]:::orchestrator
        Tools["Tools"]:::orchestrator
        Orchestrator --> ScreenAgent
        Orchestrator --> MetaAgent
        Orchestrator --> TestAgent
        Orchestrator --> VoiceAgent
        Orchestrator --> DemoAgent
        Orchestrator --> StakeholderAgent
        Orchestrator --> Tools
    end

    %% Services Layer
    subgraph "Services Layer"
        direction TB
        OpenAI["openaiService"]:::services
        Playwright["playwrightService"]:::services
        VideoSvc["videoService"]:::services
        GCPStorage["gcpStorageService"]:::services
        SupaStorage["supabaseService"]:::services
        UnifiedStorage["unifiedStorageService"]:::services
        PipelineSvc["pipelineAgentService"]:::services
        VoiceSvc["realtimeVoiceService"]:::services
        DemoRec["demoRecordingService"]:::services
    end

    %% Data & External Layer
    subgraph "Data & External"
        direction TB
        SupabaseDB["Supabase<br/>(Postgres)"]:::db
        GCPBucket["GCP Storage"]:::db
        OpenAIExt["OpenAI API"]:::external
        PlaywrightExt["Playwright"]:::external
        FFmpegExt["FFmpeg CLI"]:::external
    end

    %% Connections
    UI -->|HTTP POST| API
    API -->|invoke| Orchestrator
    Orchestrator -->|generate steps| OpenAI
    Orchestrator -->|run browser| Playwright
    Orchestrator -->|generate voiceover| OpenAI
    Orchestrator -->|merge video| VideoSvc
    VideoSvc --> FFmpegExt
    OpenAI --> OpenAIExt
    Playwright --> PlaywrightExt
    SupaStorage --> SupabaseDB
    GCPStorage --> GCPBucket
    SupaStorage --> SupabaseDB
    UnifiedStorage --> SupaStorage
    UnifiedStorage --> GCPStorage
    PipelineSvc --> Orchestrator
    API -->|WebSocket| UI
    API --> SupaStorage
    UI -->|history fetch| SupaStorage
    UI -->|download| API

    %% Click Events - Frontend
    click UI "https://github.com/jlin3/runthru/blob/main/client/index.html"
    click ConfigForm "https://github.com/jlin3/runthru/blob/main/client/src/components/ConfigurationForm.tsx"
    click ExecStatus "https://github.com/jlin3/runthru/blob/main/client/src/components/ExecutionStatus.tsx"
    click History "https://github.com/jlin3/runthru/blob/main/client/src/components/RecordingHistory.tsx"
    click QueryClient "https://github.com/jlin3/runthru/blob/main/client/src/lib/queryClient.ts"
    click Config "https://github.com/jlin3/runthru/blob/main/client/src/lib/config.ts"
    click UI "https://github.com/jlin3/runthru/blob/main/client/src/main.tsx"
    click UI "https://github.com/jlin3/runthru/blob/main/client/src/App.tsx"
    click History "https://github.com/jlin3/runthru/blob/main/client/src/pages/dashboard.tsx"

    %% Click Events - Backend
    click API "https://github.com/jlin3/runthru/blob/main/server/index.ts"
    click API "https://github.com/jlin3/runthru/blob/main/server/index.prod.ts"
    click Routes "https://github.com/jlin3/runthru/blob/main/server/routes.ts"
    click EventBus "https://github.com/jlin3/runthru/blob/main/server/eventBus.ts"

    %% Click Events - Orchestration
    click Orchestrator "https://github.com/jlin3/runthru/blob/main/packages/agent/src/index.ts"
    click ScreenAgent "https://github.com/jlin3/runthru/blob/main/packages/agent/src/agents/screenRecordAgent.ts"
    click MetaAgent "https://github.com/jlin3/runthru/blob/main/packages/agent/src/agents/metadataAgent.ts"
    click TestAgent "https://github.com/jlin3/runthru/blob/main/packages/agent/src/agents/testScriptAgent.ts"
    click VoiceAgent "https://github.com/jlin3/runthru/blob/main/packages/agent/src/agents/voiceoverAgent.ts"
    click DemoAgent "https://github.com/jlin3/runthru/blob/main/packages/agent/src/agents/demoVideoAgent.ts"
    click StakeholderAgent "https://github.com/jlin3/runthru/blob/main/packages/agent/src/agents/stakeholderAgent.ts"
    click Tools "https://github.com/jlin3/runthru/blob/main/packages/agent/src/tools/runBrowser.ts"
    click Tools "https://github.com/jlin3/runthru/blob/main/packages/agent/src/tools/planTest.ts"
    click Tools "https://github.com/jlin3/runthru/blob/main/packages/agent/src/tools/generateMetadata.ts"
    click Tools "https://github.com/jlin3/runthru/blob/main/packages/agent/src/tools/generateVoiceover.ts"
    click Tools "https://github.com/jlin3/runthru/blob/main/packages/agent/src/tools/mergeVideo.ts"
    click Tools "https://github.com/jlin3/runthru/blob/main/packages/agent/src/tools/sendToStakeholder.ts"

    %% Click Events - Services
    click OpenAI "https://github.com/jlin3/runthru/blob/main/server/services/openaiService.ts"
    click Playwright "https://github.com/jlin3/runthru/blob/main/server/services/playwrightService.ts"
    click VideoSvc "https://github.com/jlin3/runthru/blob/main/server/services/videoService.ts"
    click GCPStorage "https://github.com/jlin3/runthru/blob/main/server/services/gcpStorageService.ts"
    click SupaStorage "https://github.com/jlin3/runthru/blob/main/server/services/supabaseService.ts"
    click UnifiedStorage "https://github.com/jlin3/runthru/blob/main/server/services/unifiedStorageService.ts"
    click PipelineSvc "https://github.com/jlin3/runthru/blob/main/server/services/pipelineAgentService.ts"
    click VoiceSvc "https://github.com/jlin3/runthru/blob/main/server/services/realtimeVoiceService.ts"
    click DemoRec "https://github.com/jlin3/runthru/blob/main/server/services/demoRecordingService.ts"

    %% Click Events - Data Layer
    click SupabaseDB "https://github.com/jlin3/runthru/blob/main/shared/schema.ts"
    click SupabaseDB "https://github.com/jlin3/runthru/blob/main/scripts/setup-supabase.js"
    click GCPBucket "https://github.com/jlin3/runthru/blob/main/server/storage.ts"
    click GCPBucket "https://github.com/jlin3/runthru/tree/main/uploads/videos/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef orchestrator fill:#fff3cd,stroke:#856404,color:#856404;
    classDef services fill:#e2e3e5,stroke:#383d41,color:#383d41;
    classDef db fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
