Extension Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• wxt.config.ts
• src/entries/content/index.ts
• src/entries/background/helpers.ts
• src/entries/background/handlers/hierarchy-handlers.ts
• src/entries/background/handlers/field-handlers.ts
• CONTRIBUTING.md

Refined GitHub Projects is built as a browser extension using the WXT framework, designed to enhance GitHub Projects V2 with bulk operations and advanced sprint management. The architecture follows a strict separation of concerns between the user interface (Content Scripts) and the data processing layer (Background Service Worker) to ensure security, rate-limit compliance, and a native-feeling UX.

The extension operates entirely client-side, communicating directly with the GitHub GraphQL and REST APIs. It utilizes a sequential execution model for mutations to avoid triggering GitHub's anti-abuse mechanisms.

Sources: README.md:1-5, README.md:278-294, CONTRIBUTING.md:12-14

Core Architectural Components

The system is divided into three primary execution environments: the Content Script, the Background Service Worker, and the Extension Popup/Options pages.

System Overview Diagram

The following diagram illustrates the communication flow between the different layers of the extension and the GitHub API.

1. Content Script (UI & DOM Layer)

The Content Script is the entry point for UI enhancements. It is responsible for observing the GitHub Projects table view and injecting features like the Bulk Actions Bar and Sprint headers.

• Isolation: Injected UI is rendered within a Shadow DOM container to prevent style clashes with GitHub's native CSS.
• DOM Observation: Uses MutationObserver to detect changes in the GitHub Projects table and trigger injections.
• Interaction: Captures user actions (e.g., bulk selections, button clicks) and transmits them to the background worker via typed messages.

Sources: src/entries/content/index.ts:21-45, README.md:295-296, wxt.config.ts:24-30

2. Background Service Worker (Logic & API Layer)

The Background Service Worker acts as the central coordinator for all "heavy lifting" and API interactions. It is the only component authorized to perform write operations to the GitHub API.

• Sequential Queue: All mutations are processed through a sequential task queue. Concurrent mutations are strictly prohibited to prevent 403/429 "Abuse" rate-limiting from GitHub.
• Credential Management: Securely retrieves the Personal Access Token (PAT) from WXT Storage to authenticate requests.
• Message Handlers: Implements specific handlers for fields, hierarchy, and item resolution.

Sources: src/entries/background/handlers/field-handlers.ts:25-30, CONTRIBUTING.md:12-16, README.md:297-302

Data Flow & Communication

Communication between components is handled via a typed messaging system. The Content Script never calls the GitHub API directly.

Item Resolution Flow

When a user selects items in the DOM, the extension must resolve volatile DOM-based IDs into persistent GitHub Node IDs before any mutations can occur.

Sequential Mutation Pattern

The extension enforces a mandatory delay between API mutations to remain rate-limit safe.

Requirement	Implementation Detail
Concurrency	No Promise.all() for mutations; tasks run one by one.
Delay	A minimum of 1 second (sleep(1000)) between mutations.
Error Handling	Automatic backoff on 403 or 429 status codes.
Reporting	Progress is broadcasted back to the UI via queueStateUpdate.

Sources: src/entries/background/helpers.ts:684-706, CONTRIBUTING.md:14-22, README.md:301-302

Module Structure

The background logic is modularized to maintain small, maintainable files (typically < 400 lines).

Key Modules and Handlers

• Field Handlers: Manages repository metadata searches (Assignees, Labels, Issue Types) and project field definitions.
• Hierarchy Handlers: Manages complex issue relationships, including Parent/Sub-issue linking and "Blocked by" dependencies.
• Helpers: Contains shared logic for rate-limiting, GraphQL execution, and string parsing (e.g., parsing repo owners from URLs).

Sources: src/entries/background/handlers/field-handlers.ts:1-20, src/entries/background/handlers/hierarchy-handlers.ts:31-45, src/entries/background/helpers.ts:1-30

Configuration and Build System

The extension uses wxt.config.ts to define its manifest and build-time hooks.

Configuration	Description
Permissions	Requires storage for PAT saving and host_permissions for api.github.com and github.com.
Isolated World	Stubs out @primer/live-region-element because customElements is null in content script isolated worlds.
Manifest Hooks	Cleans web_accessible_resources to remove use_dynamic_url from CSS and merge duplicate resource entries.

Sources: wxt.config.ts:10-30, wxt.config.ts:32-60, wxt.config.ts:74-85

Architectural Summary

The architecture of Refined GitHub Projects is built on the principle of Rate-Limit Safety. By moving all API logic to a background worker and enforcing a sequential, delayed execution queue, the extension provides powerful bulk editing capabilities without risking the user's GitHub account standing. The use of WXT and Shadow DOM ensures the extension remains compatible across different browsers while maintaining a native user experience.

Sources: README.md:310-322, CONTRIBUTING.md:21-25