Architecture

PageSieve is designed to be local-first, ergonomic, and reusable. This page provides a high-level overview of the project’s architecture and its core components.

Tech Stack

The extension is built using:

  • TypeScript: Ensuring type safety across the codebase.
  • Svelte: Used for the sidebar and full-page dashboards.
  • Vite: The build tool and development server.
  • Shadcn UI: For building consistent and accessible UI components.
  • XState: For implementing main loop of extension.
  • Zod: Defining and validating scrape configurations and other schemas.

Core Components

  • Sidebar UI (packages/extension/ui/sidebar): The main interface for defining scrape configurations.

  • Content Script (packages/extension/src/content.ts): Injected into the webpage to interact with the DOM.

  • Background Script (packages/extension/src/background.ts): Manages messaging between different parts of the extension.

  • Scraping State Machine (packages/core/src/scrapeMachine.ts): state machine controlling main loop of the extension

  • DOM Inspector (packages/extension/src/dominspector.mts): Handles the click-based selection of elements.

  • Selector Engine (packages/extension/src/selectorgadget.ts): Implements the CSS selector guessing algorithm. Vendored version of cantino/selectorgadget: Go go CSS / DOM inspection.

  • Data Types (packages/core/src/schema.ts): Central location for Zod schema defining the scrape configuration.

  • Logging System (packages/core/src/logger.ts) and (packages/extension/src/logger.ts): Structured logging using LogTape, supporting relay to local environments.