How gitnasr/zolve works
Project Overview and Purpose
• The extension automates exam answering using AI backends (such as Claude and Cloudflare Workers AI) along with platform-specific logic for Microsoft Forms.
• It integrates with the Chrome browser, using content scripts, a background service worker, and React components for the options page.
• The extension leverages a build system involving Webpack for bundling, PostCSS/Tailwind for styling, and TypeScript for static typing.
File Structure to Identify Main Components
• Top-Level Files & Directories:
• The “src” folder contains the core code including AI agents (in src/ai-agents), exam platform implementations (in src/engines), Chrome-specific utilities (in src/chrome), UI components (in src/components), and the background service worker (src/Background.ts).
• “public” holds static assets like CSS and HTML used by the extension.
• Webpack configuration files (webpack/common.js, dev.js, prod.js) indicate different build profiles.
• The configuration files like package.json, tsconfig.json, and tailwind.config.js are key parts of the build and styling setup.
Main Architectural Components
a. AI Agents Layer:
• Components: AI implementations in src/ai-agents (abstract.ts, Claude.ts, Cloudflare.ts, Prompt.ts).
• Role: Interface with external AI APIs. All agents extend an abstract Agent class that defines methods like Start(), prepareHost(), and SendMessage().
b. Exam Engine Layer:
• Located under src/engines.
• Role: Handles platform-specific logic such as question scraping and answer formatting (e.g., implementations for Microsoft Forms).
c. Chrome-Specific Layer:
• Background Service Worker (src/Background.ts) manages background tasks and registers AI agents.
• Content Script (src/ContentScript.tsx) interacts with the Microsoft Forms webpage to inject actions and UI components.
• Chrome utilities (src/chrome) to handle actions and event wiring specific to Chrome’s extension APIs.
d. UI Components:
• Located under src/components for building the options page and possibly other UI elements (e.g., Claude.tsx, Cloudflare.tsx, Prompt.tsx).
• These interface components allow users to configure and customize extension features.
e. Build & Configuration Tools:
• Webpack configuration files (in webpack/ folder) for bundling.
• PostCSS and Tailwind CSS configurations for managing styles.
• TypeScript ensures type safety across the project.
f. External Services:
• AI external endpoints (for Claude and Cloudflare) and Microsoft Forms integration.
• Reverse API server for Claude.ai (mentioned in the README) is an external dependency.
Relationships and Data Flow
• Between the Content Script (triggered by right-click and keyboard commands on the exam page) and the Background Service Worker to indicate messaging.
• From the Background Service Worker to the AI Agents, where user input is processed and images are retrieved.
• From AI Agents to external API endpoints, showing outbound communication.
• Between the Options Page (React Components) and the Background Service Worker, signifying configuration changes flowing to operational components.
• From the Exam Engine components to the Content Script, representing exam-specific logic retrieving questions and formatting answers.
Applying Architectural Patterns and Design Principles
• Separation of concerns: clearly delineate layers for Chrome integration, AI business logic, exam-specific logic, and user configuration.
• Use of object-oriented principles through inheritance (AI Agents extend a common abstract class) and modular design (each folder encapsulates specific functionality).
• Dependency injection points, such as configuration components influencing which AI agent or exam engine is active.