Architecture Overview

Understand the architecture and design patterns of the Botnadzor Extension

The Botnadzor Extension is built with modern web technologies and follows a modular architecture designed for maintainability and extensibility.

Technology Stack

The extension is built with:

• WXT - Modern browser extension framework
• React 19 - UI library with React Compiler for automatic memoization
• TypeScript - Type-safe JavaScript
• TailwindCSS - Utility-first CSS framework
• Shadcn UI & Radix UI - Component libraries
• Zod - Schema validation
• Dexie - IndexedDB wrapper for data storage
• ORPC - Type-safe RPC framework
• Lucide - Icon library

Three Entrypoints

The extension has three main entrypoints, each serving a distinct purpose:

1. Background (Service Worker)

The background entrypoint (src/entrypoints/background.ts) runs as a service worker and serves as the extension’s backend.

Responsibilities:

• Registers and manages all services
• Handles data persistence and synchronization
• Manages extension configuration (root config, user config, DX config)
• Communicates with remote APIs
• Coordinates between content scripts and popup

Key Services:

• AffiliationService - Bot/spam account detection
• AuthService - Authentication management
• StaticListsService - Known bot lists management
• InspectorService - Account inspection functionality
• RegDateService - VK account registration date lookup
• CollectingService - Comment data collection
• NotificationService - Extension notifications
• And more…

All services are exposed via @webext-core/proxy-service for type-safe communication with other entrypoints.

2. Content Script

The content script (src/entrypoints/content.ts) runs on VK.com and related sites to modify the DOM.

Responsibilities:

• Detects and highlights bot accounts on pages
• Injects UI elements into VK pages
• Manages DOM modifications through the insertion system
• Provides in-page inspector and toast notifications
• Handles VK-specific page detection and navigation

Key Features:

Insertion System

The content script uses a config-driven insertion system for modular DOM modifications:

• Insertion Variants - Defined in insertion-variants.ts, each variant handles a specific type of page element:

  • =account.ts - Account profile modifications
  • =comment.ts - Comment highlighting and badges
  • =reply-form.ts - Reply form enhancements
  • =review.ts - Review element modifications

• Automatic Cleanup - Insertions are automatically cleaned up when elements are removed from the DOM

• Tailwind Prefix - Content script styles use the bn: prefix to avoid conflicts with VK’s styles

In-Page App

The in-page app (in-page-app.tsx) provides:

• Inspector UI for examining suspicious accounts
• Toast notifications for user feedback
• Welcome messages and announcements

3. Popup

The popup (src/entrypoints/popup.html and popup/app.tsx) provides the extension’s settings and information interface.

Features:

• Extension settings and configuration
• User statistics and activity data
• Announcements and notifications
• Access management and authentication

UI Structure:

• Header with extension info
• Sidebar with tab navigation
• Main content area with active tab content
• Supports light/dark theme based on system preference

Communication Between Entrypoints

The three entrypoints communicate using proxy services from @webext-core/proxy-service:

• Services are registered in the background with unique keys
• Content script and popup create proxy clients to call service methods
• All communication is type-safe and asynchronous
• Service interfaces are defined in src/shared/proxy-service-keys.ts

Key Architectural Patterns

1. Insertion System

Config-driven DOM modifications with automatic lifecycle management:

• Variants are registered in insertion-variants.ts
• Each variant defines selectors and render functions
• Automatic mounting/unmounting based on DOM changes
• Shared utilities in insertion-variants/shared/

2. Proxy Services

Type-safe communication between extension contexts:

• Background services expose methods via registerService()
• Other contexts create proxies via getService()
• Full TypeScript support with IntelliSense
• Automatic message serialization/deserialization

3. File Structure

Recursive tree approach for organizing code:

• @ prefix for internal modules (e.g., @services/, @model/)
• = prefix for variant files (e.g., =account.ts, =comment.ts)
• Shared utilities in src/shared/
• Clear separation of concerns

4. Configuration Management

Three-tier configuration system:

• Root Config - Extension-wide settings from remote API
• User Config - Per-user preferences stored locally
• DX Config - Developer experience settings (dev mode only)

Development Conventions

The codebase follows strict conventions for consistency:

React Compiler - No Manual Memoization

The React Compiler handles memoization automatically. Do NOT use:

• useMemo
• useCallback
• React.memo

Tailwind bn: Prefix

Content script insertions must use the bn: prefix for Tailwind classes:

<div className="bn:flex bn:items-center bn:gap-2">

Popup and isolated UIs use unprefixed classes.

Icons in Insertions

Import icons from lucide-static (not lucide-react) for insertions:

import { AlertTriangle } from "lucide-static";

Class Utilities

Use cn() and cnt() from @/shared/tailwindcss-helpers for conditional classes:

className={cn("base-class", condition && "conditional-class")}

Formatting Helpers

Use helpers from @/shared/formatting:

• ICU message formatting
• formatInt() - Number formatting
• formatDate() - Date formatting
• formatDateTime() - Date and time formatting

Logging

Use hierarchical logging via @/shared/logging:

const logger = getContentLogger();
logger.debug("Message with {param}", { param: value });

Error Handling

Prefer result objects over throwing errors:

return { success: false, error: "Error message" };

Instead of:

throw new Error("Error message");

Zod Schemas

• Import from zod/mini for tree-shaking
• Use z.exactOptional() instead of z.optional()

import { z } from "zod/mini";
const schema = z.object({ field: z.string().exactOptional() });

Data Flow

The extension manages data through multiple layers:

1. Remote APIs - Botnadzor backend provides bot lists and configuration
2. Background Services - Cache and process data from remote APIs
3. Local Storage - IndexedDB (via Dexie) for persistent storage
4. Content Script - Queries services for bot affiliation data
5. DOM Insertions - Render bot highlights and badges based on data

Browser Support

The extension supports:

• Chrome (and Chromium-based browsers)
• Firefox

Both browsers use Manifest V3, built with WXT’s cross-browser compatibility layer.

Next Steps

Now that you understand the architecture:

• Explore the codebase structure
• Read the full AGENTS.md guide for detailed conventions
• Start contributing to the project