🛡️ Guardian-Net: Privacy-First Digital Safety Platform

Guardian-Net is a revolutionary approach to online child and teenager safety that prioritizes education and empowerment over surveillance. Instead of tracking, recording, and reporting children's private messages to parents, Guardian-Net acts as an on-device, real-time digital safety assistant. It guides young users through context-aware, educational interventions directly at the point of communication, fostering agency and trust.

---

📖 Table of Contents

• 🔍 What is Guardian-Net?
• 🧠 Core Philosophy
• 📦 Project Structure & Components
• ✨ Key Features
• 🔎 Detection Engine
• ⚙️ Requirements & Dependencies
• 🚀 Setup & How to Run
• 🧪 Test Scenarios
• 📂 Git & GitHub Upload Readiness Check
• 🛡️ Ethical Considerations & Privacy Commitments
• 📄 License

---

🔍 What is Guardian-Net?

Guardian-Net is a prototype of an intelligent digital safety keyboard/web application designed to protect minors in real-time. Operating entirely on-device to protect user privacy, it runs incoming text through a hybrid sentiment and semantic analysis engine to classify risk levels and suggest safety interventions when potentially dangerous situations (grooming, direct threats, cyberbullying, self-harm, location leakage) are detected.

---

🧠 Core Philosophy

Guardian-Net represents a paradigm shift:

• Privacy-First: User messages are never stored, logged, or uploaded to servers. All logic is executed in the user's local runtime.
• Education Over Surveillance: Instead of locking down communication or secretly notifying guardians of specific texts, Guardian-Net teaches the user why a message is risky and allows them to self-correct.
• Trust Building: It avoids parental surveillance loops that lead to kids finding workarounds. It rebuilds healthy communication channels between teens and guardians.

---

📦 Project Structure & Components

The workspace contains both prototype mockups and a fully functional React web application:

Guardian-Net web app/
├── .gitignore                   # Root Git ignore configuration
├── .vscode/                     # VS Code local workspace configurations (ignored by Git)
├── README.md                    # Root project documentation (this file)
├── Project.docx                 # Project proposal documentation (ignored by Git)
├── pro.pdf                      # Comprehensive project proposal/spec PDF (ignored by Git)
├── files.zip                    # Archive of core files (ignored by Git)
└── files/                       # Core source files directory
    ├── PROJECT_SUMMARY.md       # High-level feature summary & roadmap
    ├── TECHNICAL_SPEC.md        # Technical design & architecture specification
    ├── IMPLEMENTATION_GUIDE.md  # Detailed step-by-step setup guides
    ├── README.md                # Component-level documentation
    ├── guardian-net.jsx         # Standalone React Component prototype
    ├── demo.html                # Standalone HTML demo (no build required, browser-ready)
    ├── package.json             # Legacy package.json for Create React App
    └── web-app/                 # Complete, modern web application (React 19 + Vite + Tailwind CSS 4)
        ├── .gitignore           # Web app-specific gitignore
        ├── .oxlintrc.json       # Oxlint linter settings
        ├── package.json         # Package configuration & modern dependencies
        ├── package-lock.json    # Package lockfile
        ├── index.html           # HTML entry point for Vite
        ├── vite.config.js       # Vite build configurations (React + Tailwind plugins)
        ├── public/              # Static assets (Favicons, SVG icons)
        └── src/                 # Application source
            ├── main.jsx         # Web application mount point
            ├── index.css        # Global CSS, Google Fonts, Tailwind 4 directives
            ├── App.jsx          # Interactive main interface & safety engine
            ├── App.css          # Main layout styles
            └── assets/          # Static images & graphics (hero backgrounds, logos)

---

✨ Key Features

1. Asynchronous Text Analysis Engine:
   • Non-blocking Architecture: Input is debounced at 300ms and analyzed asynchronously in the background. The keyboard or text field remains 100% fluid with 0ms lag.
   • Hybrid Filtering: Pre-filters obvious phrases instantly, then performs broader semantic evaluation.
   • Multi-line Evasion Detection: Input is normalized before analysis — newlines, tabs, and extra whitespace are collapsed into single spaces so phrases split across lines (e.g. "i\nwill\nkill\nyou") are correctly detected.
2. 4-Tier Risk Classification System:
   • SAFE (Green): Standard message. No interventions.
   • NUDGE (Blue): Mild bullying expression or frustration. Gentle check-in and reflection prompt.
   • HIGH (Orange): Cyberbullying (received), solicitation requests. Immediate modal popup with safety guidance.
   • CRITICAL (Red/Pulse): Self-harm patterns, direct threats, grooming. Popup with support resources (hotlines) and guardian alert.
3. Dual Detection Engines:
   • Child Distress Detector — scans messages typed by the child for self-harm signals, anger, bullying language, and general distress.
   • Stranger Threat Detector — scans messages incoming from strangers for grooming, physical threats, solicitation, and cyberbullying.
4. Visual Feedback System:
   • Visual borders dynamically alert the user. Color borders (Green → Orange/Glow → Yellow → Red) shift in real-time as they type, providing ambient, non-intrusive safety status checks.
5. Educational Interventions:
   • Modal windows offer clear explanations, reflection prompts, and support resources/hotlines (e.g., Suicide & Crisis Lifeline, NCMEC CyberTipline).
6. Gamification & Dashboard:
   • Tracks consecutive safe communication streaks, awards badges, and showcases positive choice metrics.
7. Guardian Dashboard:
   • Privacy-preserving parent alerts (event type only — never message content). Configurable detection sensitivities per threat category.

---

🔎 Detection Engine

Safe Context Whitelist

Common phrases that contain flagged words but are safe in context are whitelisted and never trigger alerts:

• "kill it in the game", "killing it", "die laughing", "gonna kill this exam", etc.

checkChildDistress — Child's Own Messages

Detects distress signals in what the child types. Runs through four ordered tiers:

Tier	Examples	Response
Crisis	"i want to die", "kill yourself", "end my life"	CRITICAL modal + crisis hotlines + breathing exercise
Anger / Threat	"i will kill you", "i hate everyone", "i'm going to hurt"	Empathy check-in modal (no punishment)
Bullying Expression	"you're so stupid", "nobody likes you"	Gentle nudge before sending
General Distress	"i feel hopeless", "nobody cares", "i hate my life"	Support modal with resources

checkStrangerThreat — Incoming Stranger Messages

Detects danger in messages sent to the child from an unknown contact. Four ordered checks:

Check	Sensitivity Gate	Examples	Alert Level
Grooming	grooming setting	"don't tell your parents", "send me pics of yourself", "our little secret"	🚨 CRITICAL
Direct Threats	threats setting	"i will kill you", "i'm at your home", "open the door", "you're dead", "watch your back", "i know where you are"	🚨 CRITICAL
Solicitation	solicitation setting	"send me some pics", "can we meet", "video call me"	⚠️ HIGH
Bullying / Harassment	Always active	"you are so ugly", "nobody likes you", "you're worthless", "go die"	🛑 HIGH

Multi-line Evasion Normalization

Both engines normalize input before pattern matching:

const lower = text.replace(/[\r\n\t]+/g, ' ').replace(/  +/g, ' ').toLowerCase();

This means splitting a phrase across lines is not an evasion technique:

i          →  detected as
will           "i will kill you"
kill
you

---

⚙️ Requirements & Dependencies

System Requirements

• Node.js: version 18.0.0 or higher (recommended: 20.x or latest LTS).
• npm: version 8.0.0 or higher.
• A modern web browser (Chrome, Firefox, Safari, Edge) with JavaScript enabled.

Dependencies (files/web-app/package.json)

Guardian-Net relies on a modern frontend stack:

• React: ^19.2.7 (UI Component model)
• React DOM: ^19.2.7 (Browser rendering)
• Lucide React: ^1.24.0 (Minimalist UI Icons)
• Tailwind CSS: ^4.3.2 (Modern CSS framework integration)
• Vite: ^8.1.1 (Next-gen frontend build tool / fast hot reloading)
• Oxlint: ^1.71.0 (Ultra-fast JavaScript/React linter)

---

🚀 Setup & How to Run

Follow these steps to launch the modern web application locally:

Option A: Running the Vite Web App (Recommended)

1. Open your terminal or command prompt.
2. Navigate to the web-app project directory:

   cd "files/web-app"

3. Install the required dependencies:

   npm install

4. Launch the local development server:

   npm run dev

5. Open your browser and navigate to the URL shown in your terminal (typically http://localhost:5173).

---

Option B: Standalone HTML (Immediate Execution)

If you wish to view a conceptual demo without installing Node.js or run-time packages:

1. Navigate to the files/ directory.
2. Double-click demo.html to open it directly in any web browser.

---

🧪 Test Scenarios

Use the Demo Scenarios panel in the sidebar, or type messages manually to test. Switch between Child and Stranger roles using the role switcher in the chat header.

Demo Scenarios (click to auto-run)

Scenario	Role	Message Sent	Expected Popup
Stranger Grooming Attempt	Stranger	"you seem so mature for your age, don't tell your parents we're talking"	🚨 CRITICAL — Grooming alert
Receive Bullying Message	Stranger	"you are so ugly and nobody likes you"	🛑 HIGH — Bullying detected popup
Child In Distress	Child	"i feel so hopeless and i hate my life"	💙 Support modal with resources
Self-Harm Language	Child	"i want to die"	🚨 CRISIS — Crisis support modal
Normal Safe Message	Child	"hey just checking in, how are you?"	✅ No alert — Safe message

Manual Test Cases

Risk Level	Input Example	Expected Behavior
Safe (Contextual)	"I'm going to kill it in this game!"	No alert — gaming slang whitelisted
High — Bullying (Stranger)	"you are so ugly and nobody likes you"	🛑 Bullying message popup
Critical — Threat (Stranger)	"i will kill you"	🚨 Threatening message popup
Critical — Threat (Stranger)	"i am at your home, open the door"	🚨 Threatening message popup
Critical — Threat (Stranger)	"you're dead, watch your back"	🚨 Threatening message popup
Critical — Self-harm (Child)	"i want to die"	🚨 Crisis support modal
Distress (Child)	"i feel hopeless and nobody cares"	💙 Support modal
Multi-line evasion	i ↵ will ↵ kill ↵ you	🚨 Detected — line breaks collapsed

---

📂 Git & GitHub Upload Readiness Check

Before publishing this repository to GitHub, verify that your local environment matches the exclusion policies set up in .gitignore.

🔍 What Will Be Uploaded (Ready for GitHub):

• files/ directory containing markdown specifications, standalone code files (guardian-net.jsx, demo.html), and the web-app source code (src/, public/, config files).
• Root configuration files (README.md, .gitignore).

🚫 What Will Be Ignored (Excluded from Upload):

• node_modules/ (All package dependencies inside files/web-app/node_modules/ will be ignored, preventing uploads of thousands of vendor files).
• dist/ and dist-ssr/ (Local production builds).
• *.local (Local environment secret configurations).
• pro.pdf & Project.docx (Heavy documentation binaries).
• files.zip & Mobile.zip (Compressed binary archives).
• .vscode/ (Local editor settings and workspace configurations).
• *.log & logs/ (System debug logs generated during development).

---

🛡️ Ethical Considerations & Privacy Commitments

Guardian-Net is designed under strict ethical parameters:

1. Local Inference: Natural language analysis occurs strictly client-side using JavaScript — no data ever leaves the browser.
2. No Snooping: The parent dashboard receives event types, but never the content of private messages, ensuring teenage agency is respected.
3. Non-Punitive Design: When a child types something concerning, Guardian-Net always allows the message to be sent. It intervenes with empathy and education, not locks or punishments.
4. Federated Learning Potential: Future iterations will support federated model fine-tuning where parameters, not private text records, are aggregated.

---

📄 License

This project is open-source and distributed under the Apache License 2.0. Feel free to use, modify, and distribute it in accordance with the terms of the license.