# chipspeak/guideframe architecture

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

- Interactive diagram: https://gitdiagram.com/chipspeak/guideframe
- Repository: https://github.com/chipspeak/guideframe

## Overview

Based on our analysis of the file tree and the README, GuideFrame is a Python-based tool designed for producing detailed walkthrough videos of projects by automating screen recording, browser interactions, and voiceover creation. It serves both as a locally executed tool and as a GitHub Action, integrating several open-source utilities like ffmpeg, gTTS, xvfb, mutagen, chromium, and Selenium.

##### Main Architectural Components
- Core Library (GuideFrame):
- Located under the “guideframe” directory. Contains modules such as:
- assembly.py (likely responsible for piecing together audio, video, and interactions)
- audio.py and video.py for media processing
- selenium.py for browser automation
- utils.py for supporting functions
- Demo/Example Scripts:
- Found in “guideframe_demos” and “selenium_demos” directories. They illustrate sample usage scenarios like the Tutors Demo, Magento Demo, and Code Walkthrough.
- Documentation and Configuration:
- “docs” folder contains all of the guides and configuration for building the documentation site.
- “.github/workflows” directory houses GitHub Actions workflows, indicating how GuideFrame can be run automatically.
- Deployment & Packaging:
- Presence of files like “pyproject.toml”, “requirements.txt”, and packaging files in the repository root; these indicate integration with PyPi and standard Python package management practices.
- Deprecated Code:

##### Relationships and Interactions Between Components
- The Core Library is the heart of the system:
- It interacts with external dependencies (ffmpeg for video processing, gTTS for voice synthesis, xvfb for virtual display, and selenium for browser control).
- The core modules (assembly, audio, video, selenium, and utils) work together to:
- Screen recordings (using ffmpeg along with xvfb),
- Automate UI interactions via Selenium (driving Chromium),
- Generate voiceovers with gTTS,
- Assemble the recorded clips and audio stream.
- Demo Modules:
- These use the core library to showcase different use cases.
- GitHub Actions:
- The workflows in .github/workflows trigger builds, renders, or automated tests (like selenium tests). They illustrate integration and continuous integration workflow.
- Documentation:
- The docs directory links to all major components, serving as the user-guide and developer documentation.

##### Important Architectural Patterns and Design Principles
- Modularity:
- The clear separation between the core code (“guideframe" directory) and the demo scripts provides an easy means to extend functionality.
- Separation of Concerns:
- Distinct responsibilities exist for media processing, browser automation, and documentation.
- Extensibility:
- Demos and examples reveal the design’s commitment to user customization.
- Integration with External Services:
- The system relies on and clearly separates third-party dependencies (ffmpeg, gTTS, selenium, etc.).

##### Relevant Technologies and External Components
- And connect external tools:
- ffmpeg: Video capture/processing
- gTTS: Text-to-speech voiceover generation
- xvfb: Virtual display setup
- Selenium & Chromium: Automated browser interactions
- Mutagen: Audio file parsing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Tools Group
    subgraph "External Tools"
        FT1("ffmpeg"):::external
        GT("gTTS"):::external
        XV("xvfb"):::external
        SE("Selenium Engine"):::external
        CB("Chromium Browser"):::external
        MU("Mutagen"):::external
    end

    %% Core Library Group
    subgraph "GuideFrame Core Library"
        Assembly("Assembly"):::core
        Audio("Audio"):::core
        Video("Video"):::core
        Selenium("Selenium"):::core
        Utils("Utils"):::core
    end

    %% Demo Scripts Group
    subgraph "Demo Scripts"
        subgraph "Code Walkthrough Demo"
            CodeDemoMD("Demo (Markdown)"):::demo
            CodeDemoScript("Demo (Python)"):::demo
        end
        subgraph "Tutors Demo"
            TutorsMD("Tutors Demo (Markdown)"):::demo
            TutorsScript("Tutors Demo (Python)"):::demo
        end
        subgraph "Selenium Demos"
            SeleniumDemoMD("Selenium Demo (Markdown)"):::demo
            SeleniumDemoScript("Selenium Demo (Python)"):::demo
            SeleniumTests("Selenium Automation Tests"):::demo
        end
    end

    %% CI/CD and Deployment
    subgraph "CI/CD & Deployment"
        Actions("GitHub Actions Workflows"):::ci
        subgraph "Deployment & Packaging"
            PyProject("pyproject.toml"):::deploy
            Requirements("requirements.txt"):::deploy
        end
    end

    %% Documentation
    Documentation("Documentation"):::doc

    %% Deprecated / Legacy Code
    subgraph "Deprecated/Legacy"
        LegacySide("Legacy wiki-test.side"):::legacy
        LegacyPy("Legacy wiki_test.py"):::legacy
    end

    %% Relationships from External Tools to Core Modules
    FT1 -->|"feeds"| Video
    XV -->|"enables"| Video
    GT -->|"supplies voice"| Audio
    MU -->|"analyzes"| Audio
    SE -->|"controls"| Selenium
    CB -->|"drives"| Selenium

    %% Core Modules interacting with Assembly (Orchestration)
    Audio -->|"processed by"| Assembly
    Video -->|"processed by"| Assembly
    Selenium -->|"reports to"| Assembly
    Utils -->|"assists"| Assembly

    %% Demo Scripts invoke Core Library functions
    CodeDemoMD -->|"calls"| Assembly
    CodeDemoScript -->|"calls"| Assembly
    TutorsMD -->|"calls"| Assembly
    TutorsScript -->|"calls"| Assembly
    SeleniumDemoMD -->|"calls"| Assembly
    SeleniumDemoScript -->|"calls"| Assembly
    SeleniumTests -->|"calls"| Assembly

    %% CI/CD triggers Selenium Tests
    Actions -->|"triggers"| SeleniumTests

    %% Documentation links to Core Library
    Documentation -->|"describes"| Assembly

    %% Deployment & Packaging feeds into Core Library
    PyProject -->|"packages"| Assembly
    Requirements -->|"installs"| Assembly

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef external fill:#FFCCCB,stroke:#000,stroke-width:2px;
    classDef demo fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef ci fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef deploy fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef doc fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef legacy fill:#F5DEB3,stroke:#000,stroke-width:2px;

    %% Click Events for GuideFrame Core Library Modules
    click Assembly "https://github.com/chipspeak/guideframe/blob/main/guideframe/assembly.py"
    click Audio "https://github.com/chipspeak/guideframe/blob/main/guideframe/audio.py"
    click Video "https://github.com/chipspeak/guideframe/blob/main/guideframe/video.py"
    click Selenium "https://github.com/chipspeak/guideframe/blob/main/guideframe/selenium.py"
    click Utils "https://github.com/chipspeak/guideframe/blob/main/guideframe/utils.py"

    %% Click Events for Demo Scripts – Code Walkthrough Demo
    click CodeDemoMD "https://github.com/chipspeak/guideframe/blob/main/guideframe_demos/guideframe_code_demo/guideframe_code_demo.md"
    click CodeDemoScript "https://github.com/chipspeak/guideframe/blob/main/guideframe_demos/guideframe_code_demo/guideframe_code_demo.py"

    %% Click Events for Demo Scripts – Tutors Demo
    click TutorsMD "https://github.com/chipspeak/guideframe/blob/main/guideframe_demos/tutors_demo/guideframe_tutors_demo.md"
    click TutorsScript "https://github.com/chipspeak/guideframe/blob/main/guideframe_demos/tutors_demo/guideframe_tutors_demo.py"

    %% Click Events for Demo Scripts – Selenium Demos
    click SeleniumDemoMD "https://github.com/chipspeak/guideframe/blob/main/selenium_demos/selenium_function_demo.md"
    click SeleniumDemoScript "https://github.com/chipspeak/guideframe/blob/main/selenium_demos/selenium_function_demo.py"
    click SeleniumTests "https://github.com/chipspeak/guideframe/blob/main/selenium_demos/selenium_automation_tests.py"

    %% Click Event for Documentation
    click Documentation "https://github.com/chipspeak/guideframe/tree/main/docs/"

    %% Click Event for GitHub Actions / CI-CD Workflows
    click Actions "https://github.com/chipspeak/guideframe/tree/main/.github/workflows/"

    %% Click Events for Deployment & Packaging
    click PyProject "https://github.com/chipspeak/guideframe/blob/main/pyproject.toml"
    click Requirements "https://github.com/chipspeak/guideframe/blob/main/requirements.txt"

    %% Click Events for Deprecated / Legacy Code
    click LegacySide "https://github.com/chipspeak/guideframe/blob/main/deprecated/wiki-test.side"
    click LegacyPy "https://github.com/chipspeak/guideframe/blob/main/deprecated/wiki_test.py"
```
