ClearTerms

ClearTerms is a privacy-first cybersecurity awareness platform that translates legal and technical jargon into human language. The system combines a real-time browser extension, an AI analysis pipeline, and a web dashboard so users can understand what a website collects, where data goes, and how risky a platform is.

Overview

ClearTerms helps everyday users make safer decisions online by turning complex privacy policies into clear, actionable summaries. Instead of only blocking threats, it educates and explains why a website is risky.

The dashboard surfaces the most important signals with minimal jargon and a clean risk narrative.

Key views focus on scan history, domain verdicts, and the most urgent alerts.

---

System Architecture

ClearTerms is built as three modular components that share a single PostgreSQL database.

Browser Extension (MV3) -> POST /api/scan -> Fastify Backend -> Supabase (Postgres + RLS)
Web Dashboard (Next.js RSC) -> /api/dashboard -> Supabase (read)

Example Flow: Website Scan

1. User visits a website; the extension Service Worker detects the event.
2. Content Script extracts privacy policy and metadata from the DOM.
3. The extension calls /api/scan on the Fastify backend.
4. Backend checks SCAN_CACHE_TTL_HOURS using a SHA-256 hash.
5. If no cache, AI analysis returns verdict, score (0-100), and findings.
6. Results are saved with service_role to bypass RLS for writes.
7. Extension renders a warning or block screen based on verdict.

Here the extension surfaces the verdict directly inside the browsing flow.

---

Tech Stack

Backend

• Fastify (Node.js 20, TypeScript) with zod validation
• Supabase (PostgreSQL + Auth + RLS) for secure multi-tenant data

Dashboard

• Next.js 16 (React 19, RSC)
• Tailwind CSS v4 and Recharts for analytics

Browser Extension

• Chromium Manifest V3
• Service Worker + Content Scripts (Vanilla JS)

---

Engineering Highlights

Deterministic Heuristic Fallback

If AI analysis fails or times out, the backend switches to deterministic heuristics (TLD risk, tracking params, raw IP URLs) and returns partial: true.

Privacy-First Meta Logging

The extension classifies only categories of form data (e.g. EMAIL, PASSWORD) and never transmits user data itself.

Retroactive Leak Alerts

When a domain is later marked as risky, backfillLeakAlertsForSite retroactively checks logs and notifies impacted users.

Defense-in-Depth with RLS

Only Fastify writes to the database using service_role, while strict RLS rules still protect user reads.

---

Data Model (Core Entities)

• auth.users / user_profiles
• groups / group_members with RBAC (admin, member, child)
• scanned_sites / site_verdicts
• scan_history
• submitted_data_log / leak_alerts

---

API Domains (Sample)

Domain	Method	Endpoint	Purpose	Auth
Auth	POST	/api/auth/login	Create access + refresh tokens	No
Auth	GET	/api/auth/me	Current user profile	Yes
Scan	POST	/api/scan	Trigger scan	Yes
Scan	POST	/api/scan/extension-result	Extension local result sync	Yes
Leaks	POST	/api/submitted-data	Submit form metadata	Yes
Leaks	GET	/api/leaks/me	Leak alerts feed	Yes
Stats	GET	/api/dashboard/stats	Dashboard analytics	Yes

---

Local Setup (Short)

Backend

cd backend
npm install
npm run seed
npm run dev

Dashboard

cd frontend
npm install
npm run dev

Extension (MV3)

Load the /wtyczka folder via chrome://extensions with Developer Mode enabled.

---