How ajskateboarder/scratch-git works
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.