# gitnasr/zolve architecture

> Architecture diagram of the GitHub repository gitnasr/zolve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gitnasr/zolve
- Repository: https://github.com/gitnasr/zolve

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Chrome Integration"
        cs["Content Script"] 
        bsw["Background Service Worker"]
        chrome["Chrome Utilities"]
    end

    subgraph "Processing Layer"
        ai["AI Agents"]
        exam["Exam Engines"]
    end

    subgraph "User Interface"
        uiReact["UI Components (React)"]
        uiOptions["Options Page"]
    end

    build["Build & Configuration Tools"]
    external["External Services/APIs"]

    %% Data Flow and Dependencies
    cs -->|"sends exam page info"| bsw
    bsw -->|"managesAIagents"| ai
    bsw -->|"usesChromeAPIs"| chrome
    exam -->|"scrapesQuestionsFormatsAnswers"| cs
    uiReact -->|"sendsConfiguration"| bsw
    uiOptions -->|"sendsConfiguration"| bsw
    ai -->|"callsAPI"| external

    build -->|"bundlesAndConfigures"| bsw
    build -->|"bundlesAssetsForUI"| uiReact
    build -->|"buildsAIModules"| ai

    %% Styles
    classDef chrome fill:#ACE7FF,stroke:#000,stroke-width:2px;
    classDef ai fill:#C2FABC,stroke:#000,stroke-width:2px;
    classDef exam fill:#FAE3C6,stroke:#000,stroke-width:2px;
    classDef ui fill:#E2C2F9,stroke:#000,stroke-width:2px;
    classDef build fill:#F5F5F5,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC2C2,stroke:#000,stroke-width:2px;

    class cs,bsw,chrome chrome;
    class ai ai;
    class exam exam;
    class uiReact,uiOptions ui;
    class build build;
    class external external;

    %% Click Events
    click ai "https://github.com/gitnasr/zolve/tree/master/src/ai-agents"
    click exam "https://github.com/gitnasr/zolve/tree/master/src/engines"
    click bsw "https://github.com/gitnasr/zolve/blob/master/src/Background.ts"
    click cs "https://github.com/gitnasr/zolve/blob/master/src/ContentScript.tsx"
    click chrome "https://github.com/gitnasr/zolve/tree/master/src/chrome"
    click uiReact "https://github.com/gitnasr/zolve/tree/master/src/components"
    click uiOptions "https://github.com/gitnasr/zolve/blob/master/src/options.tsx"
    click build "https://github.com/gitnasr/zolve/blob/master/webpack/common.js"
```
