Vite & ELEF v1.0 Architecture

This log serves as a personal reference for the Elie Labs Extension Framework (ELEF) v1.0, documenting the transition from a monolithic codebase to a modular, highly scalable Chrome extension architecture powered by Vite.

1. Core Design Philosophy (Separation of Concerns)

To achieve maximum performance and stability across all Elie Labs products, the ELEF core architecture strictly enforces the decoupling of logic and environment.

• Environment Isolation: DOM manipulation, API calls, and core algorithms are completely separated.
• Pure Logic: Core computational logic (e.g., data parsing, format conversion) must be encapsulated as “pure functions” to allow for independent unit testing outside of the browser environment.
• AI Readiness: The architecture is designed to easily plug into LLMs (Gemini, Claude, GPT), with dedicated layers reserved for context processing.

2. Standard Project Architecture

All Elie Labs product lines must uniformly follow this directory structure. This ensures zero friction and zero context switching when developers move between different extension projects.

Project-Root/
├── manifest.json       # Core config, permissions, and entry points
├── package.json        # Dependency management and scripts
├── vite.config.js      # Build engine config (Vite + CRXJS)
├── .gitignore          # Strictly exclude /dist and /node_modules
│
├── src/                # Core source code
│   ├── content.js      # Entry point (Acts purely as a Router / Event Dispatcher)
│   ├── config/         # Static configs (Constants, API endpoints, UI styles)
│   ├── utils/          # Pure functions (Math, string parsing, side-effect-free helpers)
│   ├── scrapers/       # Data extraction layer (DOM parsing and scraping)
│   ├── generators/     # Data output layer (File generation, format conversion, UI rendering)
│   └── services/       # External interaction (API calls, LLM integration, Storage)
│
├── public/             # Static assets (Icons, JSON templates)
│   └── icon16.png, icon48.png, icon128.png
│
└── dist/               # Compiled output for the Chrome Web Store (Auto-generated)

Project-Root/

• manifest.json — Core config, permissions, and entry points
• package.json — Dependency management and scripts
• vite.config.js — Build engine config (Vite + CRXJS)
• .gitignore — Strictly exclude /dist and /node_modules
• src/ — Core source code
  • content.js — Entry point (Acts purely as a Router / Event Dispatcher)
  • config/ — Static configs (Constants, API endpoints, UI styles)
  • utils/ — Pure functions (Math, string parsing, side-effect-free helpers)
  • scrapers/ — Data extraction layer (DOM parsing and scraping)
  • generators/ — Data output layer (File generation, format conversion, UI rendering)
  • services/ — External interaction (API calls, LLM integration, Storage)
• public/ — Static assets (Icons, JSON templates)
  • icon16.png, icon48.png, icon128.png
• dist/ — Compiled output for the Chrome Web Store (Auto-generated)

3. Development Flow & Tech Stack

Instead of manual builds, the ecosystem now relies on a modernized build pipeline to accelerate development and guarantee CI/CD compatibility.

• Build Engine: Vite is used for blazing-fast cold starts. We use @crxjs/vite-plugin to treat manifest.json as the actual entry point for the build process.
• HMR Experience: Running npm run dev enables true Hot Module Replacement. Vite monitors the src/ directory, instantly applying changes without needing to manually reload the extension.
• CI/CD Synergy: All pure functions in utils/ are tested in a headless environment. The final npm run build utilizes Tree-shaking and code obfuscation, preparing a production-ready dist/ folder that passes GitHub Actions checks.

🚨 Critical Reminders (Implementation Rules)

To maintain the integrity of the ELEF framework, strictly adhere to the following principles during refactoring:

• Logic Decoupling (content.js is a Router): Never write concrete business logic inside content.js. It should function purely as a switchboard, reading the current web state and deciding which scraper or generator to invoke.
• Function Purity: Complex algorithms (like coordinate calculations or layout mapping) must be moved to src/utils/. Pass DOM data in as arguments rather than letting the functions read the DOM directly. This is non-negotiable for unit testing.
• Static Asset Management: All icons, images, and fixed template files belong in the public/ directory. Do not hardcode long strings or massive Base64 data blocks directly inside the logic code.