How the pieces connect
The browser extension injects editor, My Stuff, and badge integrations into Scratch. The extension background context holds account/session state, makes authenticated API calls, maintains Socket.IO connectivity, and stores local recovery snapshots.
The Express backend exposes /apiv2 HTTP routes. Socket.IO routes authenticated project changes, chat, pointers, titles, and presence between authorized clients. Scratch Auth establishes a verified username; subsequent CoBlocks requests use backend-issued tokens.
Extension source map
| Path | Responsibility |
|---|---|
| extension/manifest.json | Manifest V3 entry points, browser minimums, permissions, content-script matches, and resources. |
| extension/background.js | Message routing, API requests, Socket.IO sessions, project linking, and IndexedDB recovery. |
| extension/background/auth.js | Scratch Auth handoff, token storage, account matching, validation, and logout. |
| extension/background/updates.js | GitHub release previews and coordinated update notices. |
| extension/injectors/ + scripts/runtime.js | Inject Scratch integrations and bridge page/background messages across browsers. |
| extension/scripts/editor.js | VM/Blockly sync, collaboration panel, cursors, chat, notifications, backpack, and Revert. |
| extension/scripts/mystuff.js + scripts/badge.js | My Stuff collaboration entries and public usage badges. |
| extension/popups/ + projects/ | Account/friends/settings popup and project workspace. |
Backend source map
| Path | Responsibility |
|---|---|
| backend/index.js | Express HTTP routes, CORS, rate limiting, project/access operations, and startup. |
| backend/WebSockets.js | Authenticated project rooms, edits, chat, pointers, and identity checks. |
| backend/utils/scratch-auth.js | Login start/callback/finish, 30-day sessions, and session invalidation. |
| backend/utils/projectAccess.js + inviteLinks.js | Ownership/membership rules and hashed expiring invite tokens. |
| backend/utils/sessionManager.js | Project state, linked copies, membership, live sessions, and change handling. |
| backend/utils/fileStorage.js + redundantStorage.js | JSON persistence, recovery mirrors, and bounded snapshots. |
| backend/utils/removeOldProjects.js | Cleanup of inactive project records. |
| backend/test/ | Authentication, access, invites, presence, pointers, backpack, recovery, and compatibility checks. |
Browser background contexts
The shared manifest declares a service worker for Chromium and background scripts for Firefox. The runtime bridge adapts page/background messaging. Browser support must be checked against the released package; a working local development manifest does not establish a store release.
Trust boundaries
Tokens and project authorization are checked by the server for HTTP and live messages. Owner-only actions cannot be safely implemented as a hidden UI button alone. The backend processes project content and chat; TLS is transport security, not end-to-end encryption.