# koffeejava/tuxtility architecture

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

- Interactive diagram: https://gitdiagram.com/koffeejava/tuxtility
- Repository: https://github.com/koffeejava/tuxtility

## Overview

##### Project type and purpose
- Tuxtility is a browser extension (for Scratch or similar block-based environments) written in JavaScript. Its goal is to inject new “blocks” and UI into the host page, with an optional permission manager (TPM) that controls what user/system information the extension may display.

##### File structure
- Top-level scripts:
- base.js – the minimal or “base” extension loader
- main.js – the full release build that includes all features (blocks, TPM, UI)
- archive/ – all past releases (1.0 → 1.5.x, betas), useful for version history but not part of the runtime
- Version-test/ – sandbox for validation tests or experimental scripts
- .github/ – issue templates and CI/workflow configs
- README.md, LICENSE, To Do.md – documentation and project roadmap

##### README for additional insights
- TPM (Tuxtility Permission Manager): modular feature for users to opt in/out of data collection
- “Flavors”: forks must comply with extension-ID, crediting, and anti-malware rules
- Release process: GitHub releases for “Full” and “Nightly” channels

a. Main components
1. Browser Extension Container
– Manifest (implicit) + base.js loader
– Content Script(s) (main.js when full release)
2. Permission Manager (TPM Module)
3. Block Registry & Injector
4. UI Layer (e.g., modal dialogs, settings panel)
5. Host Page (Scratch or target website DOM)
6. External Services
- GitHub (for version check and updates)
- Discord (support/issue reporting)
b. Relationships and data flows
– On page load, base.js loads content scripts → main.js registers blocks
– TPM intercepts any calls to collect user info → checks user preferences
– Block Injector manipulates host-page DOM to insert new block palette
– UI Layer reads/writes TPM settings (in localStorage or extension storage)
– Background/Updater polls GitHub API for new releases → notifies UI if updates exist
– User actions in UI may open external links (Discord, issues page)
c. Architectural patterns and principles
– Modular separation: core loader vs. feature modules (blocks, TPM)
– Single-page injection: all logic runs client-side in the browser context
– Extension storage for user preferences
– Versioning via separate release channels (stable vs. nightly)
d. Key technologies and frameworks
– JavaScript (ES6 modules if used)
– Browser extension APIs (chrome.* or browser.*)
– GitHub Releases & Badges for distribution
– Discord API (for support badge link)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Extension Runtime
    subgraph "Browser Extension Container"
        direction TB
        Loader["Extension Loader (base.js)"]:::script
        ContentScript["Content Script (main.js)"]:::script
    end

    %% main.js Modules
    subgraph "main.js Modules"
        direction TB
        TPM["Permission Manager (TPM)"]:::security
        BlockInjector["Block Registry & Injector"]:::script
        UI["UI Layer (Modals / Settings)"]:::script
        Updater["Background/Updater Logic"]:::script
    end

    %% Host Page Context
    HostPage["Host Page (Scratch DOM)"]:::external

    %% External Services
    GitHub["GitHub API"]:::external
    Discord["Discord Support"]:::external

    %% Documentation & CI
    subgraph "Project Docs & CI"
        direction TB
        Archive["Version History Archive"]:::persistence
        Sandbox["Experimental/Test Sandbox"]:::persistence
        IssueTemplates["CI / Issue Templates"]:::persistence
        Docs["README.md"]:::persistence
        Todo["To Do.md"]:::persistence
        License["LICENSE"]:::persistence
    end

    %% Flows
    Loader -->|"loads Content Script"| ContentScript
    ContentScript --> TPM
    TPM -->|"checks permissions"| BlockInjector
    BlockInjector -->|"injects blocks into DOM"| HostPage
    UI -->|"reads/writes settings"| TPM
    ContentScript --> UI
    Updater -->|"polls releases"| GitHub
    GitHub -->|"update available"| UI
    UI -->|"open support"| Discord

    %% Storage (extension storage)
    Storage["Extension Storage / localStorage"]:::persistence
    UI -->|"save prefs"| Storage
    TPM -->|"load prefs"| Storage

    %% Click Events
    click Loader "https://github.com/koffeejava/tuxtility/blob/main/base.js"
    click ContentScript "https://github.com/koffeejava/tuxtility/blob/main/main.js"
    click TPM "https://github.com/koffeejava/tuxtility/blob/main/main.js"
    click BlockInjector "https://github.com/koffeejava/tuxtility/blob/main/main.js"
    click UI "https://github.com/koffeejava/tuxtility/blob/main/main.js"
    click Updater "https://github.com/koffeejava/tuxtility/blob/main/main.js"
    click Archive "https://github.com/koffeejava/tuxtility/tree/main/archive/"
    click Sandbox "https://github.com/koffeejava/tuxtility/tree/main/Version-test/"
    click IssueTemplates "https://github.com/koffeejava/tuxtility/blob/main/.github/ISSUE_TEMPLATE/bug_report.md"
    click Docs "https://github.com/koffeejava/tuxtility/blob/main/README.md"
    click Todo "https://github.com/koffeejava/tuxtility/blob/main/To Do.md"
    click License "https://github.com/koffeejava/tuxtility/tree/main/LICENSE"

    %% Styles
    classDef script fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef security fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef persistence fill:#FFE4B5,stroke:#000,stroke-width:1px
```
