Architecture Documentation

Overview

Enveil is built using modern web extension technologies with a focus on performance, security, and maintainability. The architecture follows Chrome Extension Manifest V3 standards while maintaining compatibility with Firefox through Manifest V2 builds.

Technology Stack

Core Technologies

Browser Extension Architecture

System Architecture

High-Level Component Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Options Page  │    │ Background      │    │ Content Script  │
│   (React UI)    │    │ Service Worker  │    │ (UI Injection)  │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Configuration │    │ • URL Matching  │    │ • Banner Render │
│ • Group Mgmt    │    │ • Tab Events    │    │ • Overlay Render│
│ • Import/Export │    │ • Icon Updates  │    │ • Shadow DOM    │
│ • Cloud Config  │    │ • Message Route │    │ • Cloud Highlight│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │ Chrome Storage  │
                    │ API (Sync)      │
                    ├─────────────────┤
                    │ • App Config    │
                    │ • Cloud Envs    │
                    │ • Default Colors│
                    └─────────────────┘

Data Flow Architecture

User Action → Options Page → Storage API → Background Script → Content Script → Visual Update
     ↑                                           ↓
Configuration UI                            Tab Events
     ↑                                           ↓
Import/Export                              URL Matching
     ↑                                           ↓
Browser Sync                               Icon Updates

Core Components

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

Responsibilities:

Key Functions:

// Main tab checking function
async function checkAndNotifyTab(tabId: number, url: string)

// Configuration loading
async function loadConfig(): Promise<AppConfig | null>

// Icon management
async function setIconForTab(tabId: number, isMatch: boolean)

Event Handling:

2. Content Script (entrypoints/content.ts)

Responsibilities:

UI Components:

Shadow DOM Implementation:

// Create isolated shadow root
shadowHost = document.createElement('div');
shadowRoot = shadowHost.attachShadow({ mode: 'open' });

// Inject styles and UI elements
shadowRoot.innerHTML = `
  <style>/* Isolated styles */</style>
  <div class="banner-container">...</div>
`;

3. Options Page (entrypoints/options/)

Architecture Pattern: Component-based React application

Main Components:

State Management:

Key Features:

4. Utility Layer (utils/)

Matcher (utils/matcher.ts)

Core URL matching logic supporting multiple strategies:

class Matcher {
  static isMatch(site: SiteConfig, url: string, host: string): boolean
  static getMatchInfo(site: SiteConfig): string
}

Matching Strategies:

Cloud Matcher (utils/cloudMatcher.ts)

Extended matching for cloud environments:

class CloudMatcher extends Matcher {
  static isCloudAccountMatch(account: CloudAccount, url: string, host: string): boolean
  static findMatchingRoles(roles: CloudRole[], pageContent: string): CloudRole[]
  static extractRoleKeywords(content: string, roles: CloudRole[]): string[]
}

Cloud Templates (utils/cloudTemplates.ts)

Pre-configured templates for major cloud providers:

const HARDCODED_CLOUD_TEMPLATES: Record<CloudProvider, CloudTemplate> = {
  [CloudProvider.AWS_CN]: { /* AWS China configuration */ },
  [CloudProvider.AWS_GLOBAL]: { /* AWS Global configuration */ },
  [CloudProvider.AZURE]: { /* Microsoft Azure configuration */ },
  [CloudProvider.GCP]: { /* Google Cloud Platform configuration */ }
}

Data Architecture

Configuration Structure

interface AppConfig {
  browserSync: boolean;           // Cross-device sync toggle
  defaultColors: string[];        // Color palette
  settings: Setting[];            // Traditional site configurations
  cloudEnvironments?: CloudEnvironment[]; // Cloud-specific configurations
}

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

interface CloudEnvironment {
  id: string;                     // Unique identifier
  name: string;                   // Display name
  provider: CloudProvider;        // AWS, Azure, GCP, etc.
  accounts: CloudAccount[];       // Account configurations
  enable: boolean;                // Environment toggle
}

Storage Strategy

Primary Storage: Chrome Storage Sync API

Storage Events: Real-time configuration updates

storage.watch<AppConfig>('sync:appConfig', async (newConfig) => {
  // Re-evaluate all tabs when configuration changes
  const tabs = await browser.tabs.query({});
  for (const tab of tabs) {
    if (tab.id && tab.url) {
      await checkAndNotifyTab(tab.id, tab.url);
    }
  }
});

Security Architecture

Permissions Model

Content Security Policy

Style Isolation

Data Privacy

Performance Architecture

Optimization Strategies

Matching Performance:

Memory Management:

Background Script Efficiency:

Build Optimization

WXT Framework Benefits:

Extension Communication

Message Passing Architecture

// Background → Content Script
interface MatchUpdateMessage {
  action: 'MATCH_UPDATE';
  site: SiteConfig | null;
}

interface CloudMatchUpdateMessage {
  action: 'CLOUD_MATCH_UPDATE';
  cloudAccount: CloudAccount | null;
  cloudRoles: CloudRole[] | null;
}

Event Flow

  1. Tab Event: User navigates to new page
  2. Background Processing: URL matching against rules
  3. Icon Update: Extension icon reflects match status
  4. Message Dispatch: Send match results to content script
  5. UI Injection: Content script creates visual indicators
  6. Storage Sync: Configuration changes propagate across devices

Cloud Architecture Integration

Multi-Cloud Support

Provider Templates:

Dual-Layer Highlighting:

Dynamic Content Handling:

Development Architecture

Build System

Development Workflow

Testing Strategy

Scalability Considerations

Configuration Scaling

Feature Extensibility

Performance Scaling

This architecture provides a solid foundation for Enveil’s current functionality while supporting future enhancements and maintaining excellent performance and security standards.