Architecture Documentation

Overview

Enveil is a Chrome Extension built using the WXT framework. It helps developers and DevOps engineers identify different environments (dev, staging, prod) by injecting configurable visual indicators into web pages based on sophisticated matching rules.

Tech Stack

Core Architecture

1. Background Service Worker (entrypoints/background.ts)

Central coordinator handling browser events and configuration management

Key Responsibilities:

Core Algorithm:

Tab Event → Load Config → Parse URL → Match Rules → Update Icon → Notify Content Script

2. Content Script (entrypoints/content.ts)

UI injection engine with Shadow DOM isolation

Key Features:

UI Components:

3. Options Page (entrypoints/options/)

Comprehensive configuration interface with manager pattern

Manager Architecture:

Key Features:

4. Popup (entrypoints/popup/)

Quick access interface

Features:

Data Architecture

Configuration Structure

interface AppConfig {
  browserSync: boolean;           // Cross-device sync toggle
  defaultColors: string[];        // Color palette (10 predefined colors)
  settings: Setting[];            // Configuration groups
}

interface Setting {
  name: string;                   // Group name
  enable: boolean;                // Group enable/disable
  sites: SiteConfig[];            // Site rules
  defaults?: GroupDefaults;       // Group-level defaults
}

interface SiteConfig {
  enable: boolean;                // Rule enable/disable
  matchPattern: string;           // Matching strategy
  matchValue: string;             // Pattern value
  envName: string;                // Display label
  color: string;                  // Theme color
  backgroudEnable: boolean;       // Background overlay toggle
  Position: string;               // Banner position
  flagEnable: boolean;            // Banner toggle
}

Storage Strategy

Component System

Reusable Components (components/)

SwitchComponent

PreviewComponent

AddSiteModal

AddGroupModal

Matching Engine (utils/matcher.ts)

Supported Patterns

Everything (Auto-Match)

Intelligent pattern detection with multiple strategies:

Domain

URL Prefix

Exact URL

Regex

Matching Priority

  1. Check rule enable status
  2. Iterate through configuration groups (order matters)
  3. Iterate through site rules (order matters)
  4. First match wins, stop processing

Data Flow Architecture

Configuration Update Flow

User Action → Manager → AppConfig Update → Storage Save → Background Listener → 
Tab Re-evaluation → Content Script Update → UI Refresh

Page Load Flow

Tab Load → Background Detection → Config Retrieval → URL Parsing → 
Pattern Matching → Icon Update → Content Script Notification → UI Injection

Sync Flow

Config Change → Storage Event → Background Sync → All Tabs Re-evaluation → 
Cross-device Propagation (if enabled)

Security Architecture

Permissions Model

Isolation Strategy

Privacy Protection

Build & Deployment Architecture

WXT Configuration

// wxt.config.ts
export default defineConfig({
  manifest: {
    name: "Enveil",
    version: "1.0.0",
    permissions: ["storage", "tabs"],
    // Automatic Manifest V3 generation
  }
});

Build Pipeline

  1. TypeScript Compilation: Source code compilation
  2. Asset Processing: Icon generation and optimization
  3. Manifest Generation: Automatic Manifest V3 creation
  4. Bundle Creation: Extension packaging for Chrome/Firefox

Development Workflow

Performance Considerations

Optimization Strategies

Memory Management

Extension Points

Planned Enhancements

Customization Points