# teslamotors/light-show architecture

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

- Interactive diagram: https://gitdiagram.com/teslamotors/light-show
- Repository: https://github.com/teslamotors/light-show

## Overview

##### Main Components
- User Documentation & Guide – Represented by the README(s) and images that walk through the process.
- xLights Project Directory – The unzipped Tesla xLights show folder (provided in the “xlights” folder) that users load into the xLights application to create and preview sequences.
- Example Sequences – Found in the “examples” directory (with various example folders and zip files, containing paired .fseq and audio files). These show how sequences are structured.
- Validator Tool – The validator scripts (validator.py and validator executables for macOS and Windows) are provided to check .fseq files. They lie in the project root.
- Cross-Vehicle Shows – A folder with its own README that may include additional information on running shows on multiple Tesla vehicle models.
- GitHub Workflows – In the .github directory, which supports CI/CD or build automation even if it’s primarily for documentation or validation.

##### Relationships and Interactions
- The guide (README files) instructs users to download the xLights project folder and follow a workflow (sequence creation, tuning, previewing) within the xLights desktop application.
- Example folders are provided as starting points. Users unzip these examples, load them into xLights, modify them as needed, and then validate the resulting files.
- The validator tool (invoked via the command line or executables) is used to check the .fseq file’s frame count and timing before a user copies it onto a USB flash drive.
- Ultimately, after creation and validation, the light show files are placed on a correctly formatted USB flash drive (following a specific folder structure with “LightShow”), which is then used by Tesla vehicles to load and run the assembled show.
- Also, integration with the xLights application is central – the guide illustrates how to configure xLights (e.g., setting the FSEQ version to “V2 Uncompressed”) and how channels are mapped for different light behaviors.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project cleanly separates documentation/guidance (README, images, example files) from operational tools (validator.py) and resources (xlights folder, GitHub workflows).
- File-Based Configuration: The entire system is heavily driven by files – sequences (.fseq), audio (.mp3/.wav), and configuration assets (mapping files, project folders) – emphasizing the need for a correct directory structure.
- Community and Extensibility: The inclusion of multiple example shows and the cross-vehicle directory highlights a design principle where users can extend or customize their shows for different vehicles.

##### Relevant Technologies and Libraries
- xLights application – which serves as the primary tool for sequence editing and previewing.
- Python – used for the validator script, potentially to automate sequence verification.
- GitHub Actions – through the build workflows in the .github folder ensure that the repository or examples meet certain criteria during updates.

##### Elements to be Included
- Clear Labels: Mark nodes as “User Documentation (README & Images)”, “xLights Project (Source Files and Configuration)”, “Example Sequences”, “Light Show Validator”, “USB Flash Drive Packaging”, and “Tesla Vehicle” (runtime system).

##### Bringing It All Together
- How the guide supports each of these steps by linking to the exact example files (located under the “examples” folder) and instructions (in the README(s)). Also indicate the configuration dependencies (e.g., the “FSEQ Version” setting).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository Resources Subgraph
    subgraph "Repository Resources"
        direction TB
        UserDoc["User Documentation (README & Images)"]:::documentation
        GitHub["GitHub Workflows"]:::code
        Validator["Light Show Validator"]:::tool
        CrossVehicle["Cross-Vehicle Shows"]:::documentation
    end

    %% Process Flow Subgraph
    subgraph "Light Show Process"
        direction TB
        xLights["xLights Project Folder"]:::resource
        App["xLights Application (Sequence Editor)"]:::resource
        Examples["Example Sequences"]:::resource
        USB["(USB Flash Drive Packaging)"]:::storage
        Tesla["Tesla Vehicle"]:::device
    end

    %% Connections between Repository Resources and Process Flow
    UserDoc -->|"instructs"| xLights
    xLights -->|"loaded into"| App
    Examples -->|"informs"| App
    App -->|"validated by"| Validator
    Validator -->|"outputs to"| USB
    USB -->|"runs on"| Tesla

    %% Click Events for Component Mapping
    click UserDoc "https://github.com/teslamotors/light-show/blob/master/README.md"
    click UserDoc "https://github.com/teslamotors/light-show/tree/master/images/"
    click xLights "https://github.com/teslamotors/light-show/tree/master/xlights/"
    click Examples "https://github.com/teslamotors/light-show/tree/master/examples/"
    click Validator "https://github.com/teslamotors/light-show/blob/master/validator.py"
    click Validator "https://github.com/teslamotors/light-show/blob/master/validator-macos.zip"
    click Validator "https://github.com/teslamotors/light-show/blob/master/validator-windows.exe"
    click CrossVehicle "https://github.com/teslamotors/light-show/tree/master/cross-vehicle-shows/"
    click GitHub "https://github.com/teslamotors/light-show/blob/master/.github/workflows/build.yml"

    %% Styles
    classDef documentation fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef code fill:#A3E4D7,stroke:#1ABC9C,stroke-width:2px;
    classDef tool fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef resource fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
    classDef storage fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef device fill:#F5B7B1,stroke:#EC7063,stroke-width:2px;
```
