# adafruit/adafruit_wippersnapper_offline_configurator architecture

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

- Interactive diagram: https://gitdiagram.com/adafruit/adafruit_wippersnapper_offline_configurator
- Repository: https://github.com/adafruit/adafruit_wippersnapper_offline_configurator

## Overview

##### Project Type and Purpose
- This is a static, single‐page, offline web configurator for Adafruit’s Wippersnapper firmware.
- It provides a user interface (index.html + JavaScript) to assemble a `config.json` for data‐logging boards and their components without an online backend.
- A small build pipeline (Python scripts + Git submodules) hydrates the UI with up‐to‐date board, component, and firmware metadata.

##### File Structure Analysis
- Top‐Level Directories/Files:
- `.github/` – CI workflows (e.g., daily-update.yml) for automated data refresh.
- `Wippersnapper_Boards/` & `Wippersnapper_Components/` – Git submodules containing raw hardware definitions.
- `*.py` scripts – Conversion pipeline for submodule data → JSON/JS.
- `index.html`, `*.js` – Front‐end UI and data‐loading code.
- `*.json` & `*.js` data files – Generated artifacts consumed by the UI.
- `requirements.txt` – Python dependencies for build.
- Architectural Patterns:
- Static Site + Build Pipeline – No runtime server.
- Data Transformation Flow – Submodule data → converter scripts → static JSON/JS → UI.
- GitHub Pages Deployment – `index.html` + assets published to GitHub Pages.

##### Key README Insights
- The UI scripts (`load-wippersnapper-data.js`, `wippersnapper-config-builder.js`) are the core for user interactions.
- Conversion process (`convert_all_wippersnapper_definitions.py`) pulls from submodules, fetches images & firmware, then outputs `wippersnapper_*.json` and `.js`.
- CI workflow (`.github/workflows/daily-update.yml`) likely automates pulling latest boards/components and regenerating artifacts.

a. Main Components
- GitHub Submodules:
- Wippersnapper_Boards repo
- Wippersnapper_Components repo
- Build Pipeline (Local or CI):
- Python Conversion Scripts
- Node/JavaScript Build Step (if minification used)
- Generated Artifacts:
- `wippersnapper_boards.json` + `.js`
- `wippersnapper_components.json` + `.js`
- `firmware-data.js`
- Static Web Assets:
- `index.html`
- UI JavaScript (`load-wippersnapper-data.js`, `wippersnapper-config-builder.js`)
- CSS or other assets (if any)
- Client Browser:
- Loads static site from GitHub Pages or local filesystem
- Renders board/component selection UI
- Exports finalized `config.json`

b. Relationships & Interactions
- (CI) GitHub Actions → Triggers Python conversion → Commits updated artifacts → Deploys to GitHub Pages

c. Architectural Patterns & Principles
- Separation of Build‐Time vs. Runtime: All heavy processing (fetching, conversion, minification) happens at build time; runtime is purely client-side.
- Modularity: Boards and components live in separate submodules; conversion scripts are generalized to both.
- Extensibility: Adding new hardware means updating submodules or conversion logic without touching core UI.

d. Key Technologies
- Python + pip (conversion pipeline)
- JavaScript (ES6) for UI logic and data loading
- Git submodules for hardware definitions
- GitHub Actions for CI/CD
- Static hosting (GitHub Pages)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Data Sources
    subgraph "External Data Sources"
        direction TB
        Boards["Wippersnapper_Boards/"]:::external
        Components["Wippersnapper_Components/"]:::external
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        CI[".github/workflows/daily-update.yml"]:::ci
        Scripts["Python Conversion Scripts"]:::build
        Req["requirements.txt"]:::build
    end

    %% Generated Artifacts
    subgraph "Generated Artifacts"
        direction TB
        BoardsJSON["wippersnapper_boards.json"]:::artifact
        BoardsJS["wippersnapper_boards.js"]:::artifact
        ComponentsJSON["wippersnapper_components.json"]:::artifact
        ComponentsJS["wippersnapper_components.js"]:::artifact
        FirmwareJS["firmware-data.js"]:::artifact
    end

    %% Static Web Assets
    subgraph "Static Web Assets"
        direction TB
        HTML["index.html"]:::runtime
        LoadData["load-wippersnapper-data.js"]:::runtime
        ConfigBuilder["wippersnapper-config-builder.js"]:::runtime
    end

    %% Hosting Layer
    Hosting["GitHub Pages"]:::hosting

    %% Client Browser
    Browser["Client Browser"]:::client

    %% Documentation
    subgraph "Documentation & Metadata"
        direction TB
        README["README.md"]:::doc
        Gitignore[".gitignore"]:::doc
        License["LICENSE"]:::doc
    end

    %% Relationships
    Boards -->|git pull| Scripts
    Components -->|git pull| Scripts
    CI -->|triggers| Scripts
    Scripts -->|convert → JSON/JS| BoardsJSON
    Scripts -->|convert → JSON/JS| BoardsJS
    Scripts -->|convert → JSON/JS| ComponentsJSON
    Scripts -->|convert → JSON/JS| ComponentsJS
    Scripts -->|fetch firmware| FirmwareJS
    Req --> Scripts

    BoardsJSON --> HTML
    BoardsJS --> HTML
    ComponentsJSON --> HTML
    ComponentsJS --> HTML
    FirmwareJS --> HTML

    HTML --> Hosting
    LoadData --> Hosting
    ConfigBuilder --> Hosting
    Hosting -->|serves| Browser

    Browser -->|fetch data at runtime| HTML
    Browser -->|runs| LoadData
    Browser -->|runs| ConfigBuilder
    Browser -->|export| ConfigJSON["config.json"]:::client

    README --> Hosting
    Gitignore --> Hosting
    License --> Hosting

    %% Click Events
    click Boards "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/tree/main/Wippersnapper_Boards/"
    click Components "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/tree/main/Wippersnapper_Components/"
    click CI "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/.github/workflows/daily-update.yml"
    click Req "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/requirements.txt"
    click convert_all "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/convert_all_wippersnapper_definitions.py"
    click convert_boards "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/convert_boards_to_json.py"
    click convert_components "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/convert_components_to_json.py"
    click fetch_latest "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/fetch_latest_release_info_and_assets.py"
    click HTML "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/index.html"
    click LoadData "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/load-wippersnapper-data.js"
    click ConfigBuilder "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/wippersnapper-config-builder.js"
    click README "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/README.md"
    click Gitignore "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/blob/main/.gitignore"
    click License "https://github.com/adafruit/adafruit_wippersnapper_offline_configurator/tree/main/LICENSE"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef build fill:#ABEBC6,stroke:#239B56,color:#239B56
    classDef ci fill:#A9DFBF,stroke:#196F3D,color:#196F3D
    classDef artifact fill:#F5CBA7,stroke:#E67E22,color:#E67E22
    classDef runtime fill:#FCF3CF,stroke:#F1C40F,color:#B7950B
    classDef hosting fill:#D7BDE2,stroke:#8E44AD,color:#5B2C6F
    classDef client fill:#D5DBDB,stroke:#4D5656,color:#4D5656
    classDef doc fill:#F2F3F4,stroke:#B3B6B7,color:#566573
```
