# ajskateboarder/scratch-git architecture

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

- Interactive diagram: https://gitdiagram.com/ajskateboarder/scratch-git
- Repository: https://github.com/ajskateboarder/scratch-git

## Overview

##### Project Type and Purpose
- This project, called “scratch.git”, integrates Git version control into TurboWarp Desktop (a Scratch environment), enabling users (especially children) to track changes, collaborate easily, and learn about versioning without needing prior Git skills.
- The system functions by modifying the TurboWarp Desktop via a userscript and communicating with a locally running server over a WebSocket interface to perform Git operations and display diff indicators.

##### Analyzing the File Structure
- The codebase is split into two main parts:
- The Frontend, found in the “src-frontend” directory, which contains multiple subdirectories such as:
- api – provides client-side APIs to communicate with the server (including handling authentication and endpoint configurations).
- components – visual and functional UI elements like alerts, inputs, checkboxes, menus, etc.
- diff-indicators – responsible for visual diff markers showing Scratch project differences.
- modals – various pop-up interactions such as commit dialogs, diff viewers, repository configurations, project settings, and a welcome dialog.
- lib – supporting utilities and global definitions.
- Styling and type definition files (global.d.ts, styles.css, etc).
- The Backend, located in “src-server”, is written in Rust with modules like:
- main.rs – which is the server’s entry point.
- diff/ – contains code for generating and handling diffs between Scratch project versions.
- gh_auth.rs, git.rs – likely modules for authenticating with GitHub/GitLab and interfacing with the Git command line.
- Other functional modules such as those handling SB3 project parsing, zipping, and custom path handling.
- Build configurations are also present (Cargo.toml, Cargo.lock for Rust, package.json, rollup.config.js, and tsconfig.json for the frontend), hinting at a polyglot (Rust + JavaScript/TypeScript) full-stack system.

##### Key Architecture and Communication Flow
- The Frontend (userscript integrated with TurboWarp Desktop) utilizes JavaScript/TypeScript to manipulate the Git interface on the desktop. It employs:
- A structured API layer (in src-frontend/api) to send/receive data.
- Multiple UI components (in components and modals) that provide user feedback and interaction with Git commands.
- Diff indicator modules that visually communicate code differences when the Scratch project is saved.
- The Backend (Rust server) is responsible for:
- Listening for WebSocket connections from the frontend.
- Handling Git integration logic, including executing Git commands, performing diff computations (in src-server/diff), and processing commits using a Scratch-specific commit spec.
- Managing configuration and authentication.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% External Components
    A("TurboWarp Desktop"):::external
    I("Git (Local Installation)"):::external

    %% Frontend Section
    subgraph "Frontend"
        B("UI Components – src-frontend/components"):::frontend
        C("Modals – src-frontend/modals"):::frontend
        D("Diff Indicators – src-frontend/diff-indicators"):::frontend
        E("API – src-frontend/api"):::frontend
    end

    %% Backend Section
    subgraph "Backend"
        F("WS Server & Handlers – src-server/main.rs & src-server/handlers.rs"):::backend
        G("Diff Computation – src-server/diff"):::backend
        H("Git Integration – src-server/git.rs & src-server/gh_auth.rs"):::backend
    end

    %% Communication and Interaction Flow
    A -->|"InjectsScript"| B
    B -->|"triggerEvent"| E
    B -->|"openModal"| C
    E -->|"fetchDiff"| D
    E -->|"WSRequest"| F
    F -->|"WSResponse"| E
    F -->|"computeDiff"| G
    F -->|"commitAuth"| H
    H -->|"executeGit"| I

    %% Click Events
    click E "https://github.com/ajskateboarder/scratch-git/tree/main/src-frontend/api"
    click B "https://github.com/ajskateboarder/scratch-git/tree/main/src-frontend/components"
    click D "https://github.com/ajskateboarder/scratch-git/tree/main/src-frontend/diff-indicators"
    click C "https://github.com/ajskateboarder/scratch-git/tree/main/src-frontend/modals"
    click F "https://github.com/ajskateboarder/scratch-git/blob/main/src-server/main.rs and src-server/handlers.rs"
    click G "https://github.com/ajskateboarder/scratch-git/tree/main/src-server/diff"
    click H "https://github.com/ajskateboarder/scratch-git/blob/main/src-server/git.rs and src-server/gh_auth.rs"

    %% Styles
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px,stroke-dasharray: 5
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px,stroke-dasharray: 5
    classDef external fill:#ddd,stroke:#333,stroke-width:2px,stroke-dasharray: 5
```
