# Guardian Agent

## Overview

Guardian Agent is a manipulation blocker for the modern web — a Chrome extension companion web app that detects and visualizes dark patterns used by e-commerce sites to extract money from shoppers.

## Stack

- **Monorepo tool**: pnpm workspaces
- **Node.js version**: 24
- **Package manager**: pnpm
- **TypeScript version**: 5.9
- **Frontend**: React + Vite + Tailwind CSS (artifacts/guardian-agent)
- **API framework**: Express 5
- **Database**: PostgreSQL + Drizzle ORM
- **AI**: Anthropic Claude (claude-haiku-4-5) via Replit AI Integrations
- **Validation**: Zod (`zod/v4`), `drizzle-zod`
- **API codegen**: Orval (from OpenAPI spec)
- **Build**: esbuild (CJS bundle)

## Key Commands

- `pnpm run typecheck` — full typecheck across all packages
- `pnpm run build` — typecheck + build all packages
- `pnpm --filter @workspace/api-spec run codegen` — regenerate API hooks and Zod schemas from OpenAPI spec
- `pnpm --filter @workspace/db run push` — push DB schema changes (dev only)
- `pnpm --filter @workspace/api-server run dev` — run API server locally

## Pages & Features

### Landing Page (`/`)
Full marketing page: hero, stats bar, interactive browser mock demo, "How It Works", dark patterns catalog, trust leaderboard, testimonials, dual CTA

### Live Scanner (`/demo`) — Hackathon Demo Key Page
- 4 preset scenarios (Booking.com, United Airlines, Amazon, Etsy clean) — one click runs real Claude AI analysis
- Custom input mode — paste any checkout text
- Real-time animated results: all 6 dark pattern categories with evidence
- Auto-saves to DB and updates domain trust rating after each scan

### Extension Preview (`/extension`)
- Interactive browser chrome mockup showing Guardian overlay UI
- 3 switchable demo states: Booking.com (5 patterns), Etsy (clean), United Airlines (upsell gauntlet)
- Shows every Guardian action: timer warnings, auto-unchecked add-ons, rewritten buttons

### Fee Calculator (`/fee-calculator`)
- 4 quick presets (booking.com, spirit.com, airbnb.com, enterprise.com)
- Custom domain + merchant type + listed price → Claude estimates true total
- Shows itemized fee breakdown, savings opportunity, confidence level

### Command Center (`/dashboard`)
- KPI cards with 30s auto-refresh
- Live detection feed with hidden fee amounts
- Pattern distribution pie chart
- Top offenders leaderboard
- Quick action shortcuts

### Intelligence Pages
- `/trust` — Domain trust ratings with filtering
- `/trust/:domain` — Per-domain detail with scan history
- `/reports` — Detection report feed
- `/reports/:id` — Full report detail with all 6 pattern breakdowns
- `/patterns` — Dark patterns encyclopedia
- `/stats` — Analytics with bar charts and offenders table

## API Endpoints

- `POST /api/analysis/detect` — Raw Claude dark pattern analysis
- `POST /api/analysis/classify-upsell` — Classify upsell pages
- `POST /api/demo/scan` — All-in-one: detect + save report + update trust rating
- `POST /api/demo/fee-estimate` — Claude estimates true price with fee breakdown
- `GET /api/trust` — List trust ratings
- `PATCH /api/trust/:domain` — Upsert trust rating
- `GET /api/trust/:domain` — Domain detail
- `GET /api/reports` — List detection reports
- `POST /api/reports` — Create report
- `GET /api/reports/:id` — Report detail
- `GET /api/stats/summary` — Total stats
- `GET /api/stats/pattern-breakdown` — Per-type counts
- `GET /api/stats/top-offenders` — Worst domains

## Features

### Dark Patterns Detected
1. **False Urgency** — Fake countdown timers and "deal expires soon" banners
2. **False Scarcity** — Fabricated "only 1 left" and "42 people viewing" claims
3. **Confirm Shaming** — Guilt-tripping decline button text
4. **Hidden Fees** — Resort fees, service fees, and surcharges hidden until checkout
5. **Pre-Checked Add-Ons** — Travel insurance, newsletters pre-selected by default
6. **Misdirection** — Visually hidden decline options and exit paths

### App Pages
- `/` — Marketing landing page
- `/dashboard` — Command center with live stats and recent detections
- `/trust` — Domain trust ratings table
- `/trust/:domain` — Domain-specific trust profile
- `/reports` — Detection reports feed with filtering
- `/reports/:id` — Individual report detail view
- `/patterns` — Dark patterns encyclopedia (educational)
- `/stats` — Analytics with charts and top offenders

### API Endpoints
- `POST /api/analysis/detect` — AI-powered dark pattern detection (Claude)
- `POST /api/analysis/classify-upsell` — Upsell page type classification (Claude)
- `GET/PUT /api/trust/:domain` — Domain trust ratings
- `GET/POST /api/reports` — Detection reports
- `GET /api/stats/summary` — Overall statistics
- `GET /api/stats/pattern-breakdown` — Pattern type counts
- `GET /api/stats/top-offenders` — Most manipulative domains

## DB Schema

- `trust_ratings` — Per-domain trust scores and manipulation history
- `detection_reports` — Individual dark pattern scan results

## Architecture Notes

- AI integration uses Replit AI Integrations proxy for Anthropic — no API key needed
- No PII sent to AI: only anonymized page text for classification
- Frontend imports hooks from `@workspace/api-client-react` (generated via Orval)
- Backend imports Zod validators from `@workspace/api-zod` (generated via Orval)