Here's the README.md for StudyGuard:

# StudyGuard

## Production build and Chrome Web Store submission

Run these commands from the project folder:

```bash
npm test
npm run build

The upload package is the contents of the generated dist folder. Zip the contents of dist so that manifest.json is at the root of the ZIP file.

For local testing, open chrome://extensions, enable Developer mode, choose Load unpacked, and select dist. Test the popup, side panel, selection explanation, dictionary lookup, LinkGuard, clip saving, options, and context menus in a normal http or https tab.

To publish, create or sign in to a Chrome Web Store developer account, pay the one-time registration fee if required, select Add new item, upload the ZIP, complete the Store Listing, Privacy, Distribution, and Test instructions sections, then submit for review. Do not upload the project folder itself or a ZIP with an extra parent folder.

The repository includes PNG icons in icons/ and the manifest references 16, 32, 48, and 128 pixel icon entries. Review the generated icons and replace them with your final brand artwork if desired before publishing.

How the files connect

manifest.json is the entry point. It starts src/background/service-worker.js, opens src/popup/popup.html from the toolbar, opens src/sidepanel/sidepanel.html for the main workspace, and opens src/options/options.html for settings. It also injects src/content/content.js into regular HTTP/HTTPS pages.

The content script reads the current selection and sends messages to the service worker. The service worker routes messages, opens the side panel, and delegates clip creation to src/features/webclipper/webclipper.js, URL checks to src/features/linkguard/linkguard.js, and explanations to src/features/explain/explain.js. The Research tab uses src/features/research/research.js for project creation and clip lookup. These feature modules persist data in Chrome local storage. The feature modules load all JSON through src/data/data-loader.js: explanation-rules.json provides subject knowledge and dictionary.json provides general vocabulary definitions and word forms.

Link checks follow the same path through src/features/linkguard/linkguard.js, which loads the risk, suspicious-pattern, TLD, and trusted-domain JSON files. The lower-level modules in src/storage/ provide reusable wrappers for clips, projects, settings, and raw local/sync storage. They are available for future consumers and tests, while the current domain feature modules use their own storage helpers. Settings persist through Chrome's storage.sync API.

A Rule-Based Web Research and Learning Assistant for Students

StudyGuard is a Chrome extension designed to provide students with a centralized research and learning environment directly inside their browser. It combines text explanation, web clipping, research organization, and URL security analysis into a single, data-driven tool.

---

📚 Table of Contents

• Problem Statement
• Solution
• Features
• Architecture
• Data-Driven Design
• Public APIs
• Installation
• Usage
• Project Structure
• Testing
• Contributing
• License

---

🎯 Problem Statement

Students increasingly depend on the internet for research, but they face several challenges:

• Complex Language — Difficult technical or academic language can be hard to understand
• Information Overload — Useful information gets lost among many browser tabs
• Poor Saving Habits — Students save entire webpages instead of specific needed information
• Disorganization — Research sources become difficult to organize and retrieve
• Security Risks — Students may encounter suspicious or misleading links while researching

---

💡 Solution

StudyGuard provides four integrated systems within a Chrome extension:

1. 📖 Explain This

A rule-based text-processing system that provides simpler explanations of recognized terms and concepts using a JSON knowledge base.

2. 📌 WebClipper

Allows students to select and save useful webpage content with source, URL, timestamp, notes, and research project association.

3. 📚 Research Organizer

Helps students organize saved clips, webpages, notes, tabs, subjects, and research projects in a structured manner.

4. 🛡️ LinkGuard

Uses rule-based URL analysis to identify potentially suspicious characteristics including unusual domains, URL obfuscation, IP-based URLs, and suspicious patterns.

---

🏗️ Architecture

High-Level Architecture

                         STUDYGUARD
                             │
             ┌───────────────┼───────────────┐
             │               │               │
          Webpage           UI          Data Sources
             │               │               │
       content.js       popup/sidepanel   JSON + Public APIs
             │               │               │
             └───────────────┼───────────────┘
                             │
                         FEATURES
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
       Explain           WebClipper         LinkGuard
     (dictionaryapi.dev        │          (URLhaus +
      + local rules)           │        Safe Browsing +
          │                    │          local rules)
          └──────────────────┼──────────────────┘
                             │
                       Research Organizer
                             │
                             ▼
                         Storage
                             │
                     Chrome Storage /
                         IndexedDB

Data Flow

Webpage → Content Script → Features → Data Loader → Local JSON (rules/fallback)
                │                          │
                │                          └→ Public APIs (dictionaryapi.dev, URLhaus, Safe Browsing)
                ▼
           User Actions → Storage Layer → Chrome Storage/IndexedDB

---

📊 Data-Driven Design

Core Principle

Curated JSON still defines configuration and subject-specific knowledge (explanation-rules, risk-rules, subjects). Live public APIs now supply general-purpose data (dictionary definitions, URL threat intelligence) so that data stays current instead of going stale in a static file. JavaScript contains the algorithms and application logic.

Data Directory

Configuration, curated subject knowledge, and offline fallbacks live in /data/ as JSON files:

data/
├── explanation-rules.json    # Explain This subject knowledge base (curated, local)
├── dictionary.json           # Offline fallback only - used if the dictionary API is unreachable
├── subjects.json             # Academic subjects and categories
├── suspicious-patterns.json  # Local heuristic indicators (offline fallback / secondary signal)
├── suspicious-tlds.json      # Local heuristic indicators (offline fallback / secondary signal)
├── trusted-domains.json      # Local heuristic indicators (offline fallback / secondary signal)
├── settings.json             # Default configuration
├── ui-messages.json          # User-facing text messages
└── risk-rules.json           # LinkGuard scoring rules

Public APIs

Two features now call live, public APIs instead of relying solely on bundled JSON:

• Explain This — general vocabulary definitions come from dictionaryapi.dev (free, no API key). Results are cached locally. Subject-specific terms still come from the curated explanation-rules.json. If the API call fails (e.g. offline), StudyGuard falls back to the bundled dictionary.json snapshot automatically.
• LinkGuard — URLs are checked against URLhaus (free, no API key) by default. You can optionally add a free Google Safe Browsing API key in Options for a second, independent threat-intelligence source. The local rule-based heuristics (risk-rules.json, suspicious-patterns.json, suspicious-tlds.json, trusted-domains.json) still run as a secondary signal and as the offline fallback when neither online source is reachable.

Recorder & Media Storage

The Recorder tab lets students record their screen, webcam, or audio only, using the browser's built-in MediaRecorder API - no built-in length limit, export at any point.

• Screen — captures the screen/window/tab the student picks, with an option to mix in the microphone.
• Webcam — camera + microphone.
• Audio only — microphone only, for quick voice notes or podcasts.

Recordings can be saved to a study zone (shows up under that zone's Media tab) and/or exported as a .webm file to edit elsewhere. StudyGuard does not include a video editor — the Recorder tab links to a few free, open-source options (Shotcut, Kdenlive, OpenShot) for trimming/editing exported recordings.

Recordings are stored as raw Blobs in IndexedDB (src/utils/recordings-db.js) rather than chrome.storage.local, which is capped at 10MB by default and isn't designed for binary data. Combined with the unlimitedStorage manifest permission, recordings are limited only by available disk space.

Study zone notes can be exported as a standalone .html file at any time via the Export button in the Notes tab.

Google Drive Backup

Options → Storage → Google Drive lets a student connect their Google account and back up a study zone's notes, clips, and recordings to a "StudyGuard Backups" folder in their Drive (per-zone subfolders, e.g. "StudyGuard Backups/Biology 101"). The Recorder tab also has a "Back Up All to Drive" button covering every saved recording at once.

This uses chrome.identity.getAuthToken() with the drive.file OAuth scope

• StudyGuard can only see or manage files it creates itself, never anything else in the user's Drive. To enable it, you need to configure your own Google Cloud OAuth Client ID in manifest.json's oauth2.client_id field (see the Google Cloud Console setup docs for extensions using the Chrome Identity API). Without a configured Client ID, the Connect button in Options will show a connection error.

Adding New Data

To add new curated explanations, security rules, or subjects:

1. Edit the appropriate JSON file in /data/
2. No JavaScript changes required
3. Reload the extension
4. New data is immediately available

Example: Adding a New Explanation

Add to data/explanation-rules.json:

{
  "term": "mitosis",
  "category": "biology",
  "simplified_explanation": "Cell division process where one cell becomes two identical cells",
  "related_terms": ["cell division", "chromosomes", "nucleus"]
}

The Explain This feature will automatically recognize and explain the new term without code modifications.

---

🚀 Installation

Development Installation

1. Clone the repository:

git clone https://github.com/yourusername/studyguard.git
cd studyguard

2. Open Chrome and navigate to:

chrome://extensions/

3. Enable "Developer mode" (toggle in top-right corner)

4. Click "Load unpacked"

5. Select the StudyGuard project directory

6. The extension should now appear in your toolbar

Building for Production

# Create production build (if using build tools)
npm run build

# Package the extension
npm run package

---

📖 Usage

Quick Actions (Popup)

Click the StudyGuard icon for quick access to:

• Explain selected text
• Save current selection
• Check current page URL
• Open Research Organizer

Main Interface (Side Panel)

Press Ctrl+Shift+S (Windows/Linux) or Cmd+Shift+S (Mac) to open the side panel.

Keyboard Shortcuts

Action	Windows/Linux	Mac
Toggle Side Panel	Ctrl+Shift+S	Cmd+Shift+S
Explain Selection	Ctrl+Shift+E	Cmd+Shift+E
Save Clip	Ctrl+Shift+C	Cmd+Shift+C

Explain This

1. Select text on any webpage
2. Right-click and select "Explain with StudyGuard"
3. View simplified explanation in the side panel

WebClipper

1. Select text on a webpage
2. Click "Save Clip" or use keyboard shortcut
3. Add notes and tags
4. Assign to a research project
5. Save for later retrieval

Research Organizer

• Create projects for different subjects
• Organize clips by project or tags
• Search through saved research
• Export research data

LinkGuard

LinkGuard automatically analyzes URLs when:

• Hovering over links
• Clicking links
• Manually entering URLs for checking

---

📁 Project Structure

StudyGuard/
│
├── manifest.json           # Chrome extension configuration
├── README.md              # Project documentation
├── LICENSE                # License file
│
├── icons/                 # Extension icons
│   ├── icon16.png
│   ├── icon32.png
│   ├── icon48.png
│   └── icon128.png
│
├── src/
│   ├── background/        # Background service worker
│   │   └── service-worker.js
│   │
│   ├── content/           # Webpage interaction
│   │   ├── content.js
│   │   └── content.css
│   │
│   ├── popup/             # Extension popup
│   │   ├── popup.html
│   │   ├── popup.css
│   │   └── popup.js
│   │
│   ├── sidepanel/         # Main interface
│   │   ├── sidepanel.html
│   │   ├── sidepanel.css
│   │   └── sidepanel.js
│   │
│   ├── options/           # Settings page
│   │   ├── options.html
│   │   ├── options.css
│   │   └── options.js
│   │
│   ├── features/          # Core features
│   │   ├── explain/       # Explain This
│   │   ├── webclipper/    # WebClipper
│   │   ├── research/      # Research Organizer
│   │   └── linkguard/     # LinkGuard
│   │
│   ├── storage/           # Data persistence
│   │   ├── storage.js
│   │   ├── clips.js
│   │   ├── projects.js
│   │   └── settings.js
│   │
│   ├── data/              # Data loading
│   │   └── data-loader.js
│   │
│   └── utils/             # Helper functions
│       ├── constants.js
│       ├── dom.js
│       ├── url.js
│       ├── dates.js
│       └── sanitize.js
│
├── data/                  # JSON data files
│   ├── explanation-rules.json
│   ├── subjects.json
│   ├── suspicious-patterns.json
│   ├── suspicious-tlds.json
│   ├── trusted-domains.json
│   ├── settings.json
│   ├── ui-messages.json
│   └── risk-rules.json
│
├── assets/                # Non-code resources
│   ├── screenshots/
│   └── illustrations/
│
└── tests/                 # Test files
    ├── explain/
    ├── linkguard/
    ├── webclipper/
    ├── research/
    └── storage/

---

🧪 Testing

Running Tests

# Run all tests
npm test

# Run specific test suites
npm test -- --suite=explain
npm test -- --suite=linkguard
npm test -- --suite=webclipper
npm test -- --suite=research
npm test -- --suite=storage

Test Coverage

• Explain Tests — Verify text processing, term matching, and explanation generation
• LinkGuard Tests — Validate URL analysis, pattern detection, and risk scoring
• WebClipper Tests — Test clip creation, storage, and retrieval
• Research Tests — Validate project management, searching, and filtering
• Storage Tests — Verify data persistence and retrieval

---

🔒 Security

No AI/ML

StudyGuard does not use any form of AI or machine learning:

• ❌ No AI APIs
• ❌ No external AI services
• ❌ No machine learning models
• ✅ Deterministic, rule-based processing
• ✅ Public data APIs (dictionary lookups, URL threat intelligence) + local JSON knowledge base
• ✅ Transparent algorithms

Data Privacy

• All user data (clips, projects, notes, settings, check history) stored locally
• No StudyGuard-operated servers or accounts
• No tracking or analytics
• Explain This and LinkGuard call outbound public APIs (dictionaryapi.dev, URLhaus, and optionally Google Safe Browsing) to look up the word or URL you're checking - see Public APIs above for details. No clip content, notes, or research data is ever sent to these APIs.
• Works offline: if a public API is unreachable, both features fall back to their bundled local JSON data automatically

URL Security

LinkGuard combines two signals:

• Online threat intelligence - live lookups against URLhaus (and optionally Google Safe Browsing) to catch known-malicious URLs
• Local rule-based analysis - domain reputation, suspicious pattern detection, TLD verification, punycode/IP-literal detection, and risk score calculation, used as a secondary signal and offline fallback

---

🎓 Computer Science Concepts Demonstrated

This project demonstrates several important CS concepts:

• Algorithms — URL analysis, searching, filtering, scoring, text processing
• Data Structures — Projects, collections, indexes, tags, relationships
• Information Retrieval — Searching and retrieving saved research
• String Processing — Analyzing webpage text and URLs
• Database Systems — Chrome Storage and IndexedDB
• Cybersecurity — Rule-based URL risk analysis
• Software Engineering — Modular architecture, testing, separation of concerns
• Browser Programming — Chrome Extension APIs

---

🤝 Contributing

Adding New Features

1. Create feature directory in src/features/
2. Add necessary JSON data files
3. Implement feature logic
4. Add tests
5. Update documentation

Adding New Data

1. Edit appropriate JSON file in /data/
2. Follow existing JSON structure
3. Test the feature
4. No code changes needed

Code Style

• Use ES6+ JavaScript
• Follow existing patterns
• Keep data in JSON
• Keep logic in JavaScript
• Write tests for new features
• Document all functions

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Chrome Extension APIs
• JSON Schema
• Open source community

---

📞 Support

For issues, questions, or contributions:

• Open an issue
• Submit a pull request
• Contact the development team

---

StudyGuard — Making web research safer and more organized for students.

This README provides comprehensive documentation for your Computer Science project, covering all aspects from problem statement to technical implementation details.