# max-eee/neopass architecture

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

- Interactive diagram: https://gitdiagram.com/max-eee/neopass
- Repository: https://github.com/max-eee/neopass

## Overview

##### Project type and purpose
- This is a Chrome browser extension (“NeoPass Free”) designed to bypass exam‐portal restrictions, inject AI-powered assistance into pages, and provide a popup UI and DevTools panel for configuration.
- Purpose: intercept page events, inject helper scripts, communicate with AI providers (OpenAI, Gemini, Claude, or custom) and present answers or paste capabilities.

##### File structure
- Top level:
- manifest.json — Chrome extension manifest declaring scripts, UI, permissions
- contentScript.js — entry point for injection into web pages
- devtools.js — sets up a custom DevTools panel for advanced features
- popup.html / popup.js — browser toolbar UI for settings and manual triggers
- worker.js — background/service worker handling long-lived tasks and API calls
- data/ — static assets and injection modules (anti-debug, chatbot, exam bypass, etc.)
- metadata.json, nptel.txt, data/nptel.json — configuration and dataset for NPTEL integration
- Recognize the extension architecture:
- Manifest wires up background (worker.js), content scripts, popup UI, and DevTools
- Data folder modules are loaded dynamically by contentScript.js or worker.js
- Message passing via chrome.runtime and chrome.tabs APIs

##### README for additional insights
- Confirms multiple AI providers, free vs. Pro modes, feature set (MCQ solver, paste override, tab switch bypass).
- Encourages dynamic script injection for different portals and NPTEL data extraction.

a. Main components
1) Chrome Manifest – orchestrator
2) Background / Service Worker (worker.js) – handles:
- API key storage & crypto
- Outbound requests to AI endpoints
- Rate-limit logic
3) Content Scripts (contentScript.js + data/inject/*.js) – injected into exam pages to:
- Override prohibited actions (paste, right-click, tab switch)
- Load AI-powered chatbot overlay
- Insert logic for MCQ extraction and submission
4) Popup UI (popup.html / popup.js) – user interface for:
- Entering API key
- Choosing provider
- Testing connection
- Switching to Pro tab or login
5) DevTools Panel (devtools.js) – optional settings/debug interface in Chrome DevTools
6) Data Storage – localStorage or chrome.storage to persist API keys, user settings, nptel.json
7) External Services – AI provider endpoints (OpenAI, Google Gemini, Anthropic Claude, or custom)
b. Relationships and interactions
- Content scripts auto-injected on matching exam domains via manifest rules → they send initialization messages to worker.js.
- worker.js retrieves API key + provider from storage → makes HTTP calls to AI endpoint → returns suggestions.
- content scripts render suggestions (chatbot overlay, autotype, MCQ answers).
- For DevTools: devtools.js registers a panel → communicates with background to debug or tweak injection.
- Data folder injection modules are loaded on demand by contentScript.js based on the portal.
c. Architectural patterns & principles
- Chrome Extension MVC-like pattern:
- View layer: Popup UI + Chatbot overlay
- Controller: content scripts
- Model: background/service worker + storage + external API
- Loose coupling via message passing (chrome.runtime.sendMessage, onMessage).
- Modular injection: each data/inject script is a plugin for a specific bypass or enhancement.
d. Key technologies & libraries
- Chrome Extension APIs: runtime, tabs, storage, devtools
- Fetch API / XHR for HTTP calls
- Vanilla JS modules under data/inject
- Manifest v3 service worker (worker.js)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Manifest context
    subgraph "Manifest Context"
        Manifest["Manifest"]:::core
    end

    %% Background Worker context
    subgraph "Background Worker Context"
        Worker["Background Worker"]:::background
    end

    %% Page context with content scripts and injection modules
    subgraph "Page Context"
        CS["Content Script"]:::content

        subgraph "Injection Modules"
            AAD["Anti‐Anti‐Debug"]:::inject
            Chatbot["Chatbot Overlay"]:::inject
            CoreUtil["Core Utilities"]:::inject
            Paste["Paste Override"]:::inject
            Copy["Copy Override"]:::inject
            Exam["Exam Bypass"]:::inject
            Iso["Isolation Helper"]:::inject
            MainLoad["Main Loader"]:::inject
            RightClick["Right‐Click Override"]:::inject
            ScreenShare["Screen‐Share Bypass"]:::inject
            subgraph "Mock Code"
                MinBG["minifiedBackground.js"]:::inject
                MinCS["minifiedContent-script.js"]:::inject
                MockMan["mock_manifest.json"]:::inject
                Rules["rules.json"]:::inject
            end
        end
    end

    %% Popup UI context
    subgraph "Popup UI Context"
        PopupHTML["popup.html"]:::ui
        PopupJS["popup.js"]:::ui
    end

    %% DevTools context
    subgraph "DevTools Context"
        DevTools["DevTools Panel"]:::devtools
    end

    %% Storage context
    subgraph "Storage"
        Storage["chrome.storage/localStorage"]:::storage
        Metadata["metadata.json"]:::storage
        NPTELTxt["nptel.txt"]:::storage
        NPTELJSON["data/nptel.json"]:::storage
    end

    %% External services
    AI["AI Provider Endpoints"]:::external

    %% Connections
    Manifest --> Worker
    Manifest --> CS
    Manifest --> PopupHTML
    Manifest --> PopupJS
    Manifest --> DevTools

    PopupJS -->|"save settings"| Storage
    PopupJS -->|"send config"| Worker

    CS <-->|"sendMessage / onMessage"| Worker
    Worker -->|"HTTP requests"| AI
    CS -->|"render overlay"| Chatbot

    CS -.->|"dynamic load"| AAD
    CS -.->|"dynamic load"| Chatbot
    CS -.->|"dynamic load"| CoreUtil
    CS -.->|"dynamic load"| Paste
    CS -.->|"dynamic load"| Copy
    CS -.->|"dynamic load"| Exam
    CS -.->|"dynamic load"| Iso
    CS -.->|"dynamic load"| MainLoad
    CS -.->|"dynamic load"| RightClick
    CS -.->|"dynamic load"| ScreenShare
    CS -.->|"dynamic load"| MinBG
    CS -.->|"dynamic load"| MinCS
    CS -.->|"dynamic load"| MockMan
    CS -.->|"dynamic load"| Rules

    DevTools -->|"communicate via runtime"| Worker

    Storage --> Worker

    %% Click events for component mapping
    click Manifest "https://github.com/max-eee/neopass/blob/main/manifest.json"
    click Worker "https://github.com/max-eee/neopass/blob/main/worker.js"
    click CS "https://github.com/max-eee/neopass/blob/main/contentScript.js"
    click AAD "https://github.com/max-eee/neopass/blob/main/data/inject/anti-anti-debug.js"
    click Chatbot "https://github.com/max-eee/neopass/blob/main/data/inject/chatbot.js"
    click CoreUtil "https://github.com/max-eee/neopass/blob/main/data/inject/content.js"
    click Paste "https://github.com/max-eee/neopass/blob/main/data/inject/customPaste.js"
    click Copy "https://github.com/max-eee/neopass/blob/main/data/inject/copyOverride.js"
    click Exam "https://github.com/max-eee/neopass/blob/main/data/inject/exam.js"
    click Iso "https://github.com/max-eee/neopass/blob/main/data/inject/isolated.js"
    click MainLoad "https://github.com/max-eee/neopass/blob/main/data/inject/main.js"
    click RightClick "https://github.com/max-eee/neopass/blob/main/data/inject/rightclickmenu.js"
    click ScreenShare "https://github.com/max-eee/neopass/blob/main/data/inject/screenshare.js"
    click MinBG "https://github.com/max-eee/neopass/blob/main/data/inject/mock_code/minifiedBackground.js"
    click MinCS "https://github.com/max-eee/neopass/blob/main/data/inject/mock_code/minifiedContent-script.js"
    click MockMan "https://github.com/max-eee/neopass/blob/main/data/inject/mock_code/mock_manifest.json"
    click Rules "https://github.com/max-eee/neopass/blob/main/data/inject/mock_code/rules.json"
    click PopupHTML "https://github.com/max-eee/neopass/blob/main/popup.html"
    click PopupJS "https://github.com/max-eee/neopass/blob/main/popup.js"
    click DevTools "https://github.com/max-eee/neopass/blob/main/devtools.js"
    click NPTELTxt "https://github.com/max-eee/neopass/blob/main/nptel.txt"
    click NPTELJSON "https://github.com/max-eee/neopass/blob/main/data/nptel.json"
    click Metadata "https://github.com/max-eee/neopass/blob/main/metadata.json"
    click Storage "https://github.com/max-eee/neopass/tree/main/data/"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px;
    classDef background fill:#bbf,stroke:#033,stroke-width:1px;
    classDef content fill:#bfb,stroke:#036,stroke-width:1px;
    classDef inject fill:#efe,stroke:#070,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ui fill:#ffb,stroke:#b60,stroke-width:1px;
    classDef devtools fill:#fcf,stroke:#939,stroke-width:1px;
    classDef storage fill:#ddf,stroke:#339,stroke-width:1px;
    classDef external fill:#cfc,stroke:#393,stroke-width:1px,stroke-dasharray: 2 2;
```
