# skymahnoor/prompt_lense architecture

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

- Interactive diagram: https://gitdiagram.com/skymahnoor/prompt_lense
- Repository: https://github.com/skymahnoor/prompt_lense

## Overview

PromptLens is primarily a local Chrome extension that intercepts AI prompt submission, detects PII, warns the user, then masks, permits, or cancels the send while recording the decision. Its extension dashboard supports history, analytics, settings, and export; the optional Next.js viewer manually imports exported JSON and stores it locally. Extension internals are only partially sampled, so documented flows are cited to the README; viewer/API links use the sampled source excerpts.

Main entry points: [`src/app/page.tsx`](https://github.com/skymahnoor/prompt_lense/blob/main/src/app/page.tsx) (Viewer dashboard shell), [`src/lib/db.ts`](https://github.com/skymahnoor/prompt_lense/blob/main/src/lib/db.ts) (Viewer database), [`extension/content.js`](https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js) (Prompt interception), [`extension/dashboard.js`](https://github.com/skymahnoor/prompt_lense/blob/main/extension/dashboard.js) (Extension dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ext["Browser protection"]
  node_content["Prompt interception<br/>[content.js]"]
  node_engine["PII detection and masking<br/>[pii-engine.js]"]
  node_warning["PII warning and choices<br/>[content.js]"]
  node_eventlog["Local interception history<br/>[content.js]"]
  node_storage[("Chrome local storage")]
  node_background["Badge counter<br/>[background.js]"]
end

subgraph group_localui["Extension interface"]
  node_popup["Quick toggle and stats<br/>[popup.js]"]
  node_extdash["Extension dashboard<br/>[dashboard.js]"]
  node_export["JSON export and import<br/>[dashboard.js]"]
end

subgraph group_viewer["Optional web viewer"]
  node_webapp["Viewer dashboard shell<br/>[page.tsx]"]
  node_overview["Analytics overview<br/>[overview.tsx]"]
  node_history["Searchable event history<br/>[history.tsx]"]
  node_settings["Import and settings<br/>[settings-panel.tsx]"]
end

subgraph group_api["Viewer API and storage"]
  node_eventsapi["Event API<br/>[route.ts]"]
  node_statsapi["Statistics API<br/>[route.ts]"]
  node_seedapi["Demo data API<br/>[route.ts]"]
  node_healthapi["Health endpoint<br/>[route.ts]"]
  node_database[("Viewer database<br/>[db.ts]")]
end

node_user(("Prompt user"))
node_ai["AI chat site"]
node_webuser(("Viewer user"))

node_user -->|"submits prompt"| node_content
node_content -->|"detects and masks"| node_engine
node_content -->|"opens warning"| node_warning
node_warning -->|"sends masked prompt"| node_ai
node_warning -->|"records decision"| node_eventlog
node_eventlog -->|"stores locally"| node_storage
node_background -.->|"reads events"| node_storage
node_popup -->|"reads local stats"| node_storage
node_extdash -->|"reads history"| node_storage
node_extdash -->|"exports and imports"| node_export
node_user -->|"reviews activity"| node_extdash
node_webuser -->|"chooses JSON file"| node_settings
node_settings -.->|"imports events"| node_eventsapi
node_webapp -->|"fetches statistics"| node_statsapi
node_webapp -->|"renders overview"| node_overview
node_webapp -->|"renders history"| node_history
node_webapp -->|"renders settings"| node_settings
node_history -->|"fetches events"| node_eventsapi
node_eventsapi -->|"reads and writes"| node_database
node_statsapi -->|"reads events"| node_database
node_seedapi -->|"creates demo events"| node_database
node_healthapi -.-> node_database

click node_content "https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js"
click node_engine "https://github.com/skymahnoor/prompt_lense/blob/main/extension/lib/pii-engine.js"
click node_warning "https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js"
click node_eventlog "https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js"
click node_background "https://github.com/skymahnoor/prompt_lense/blob/main/extension/background.js"
click node_popup "https://github.com/skymahnoor/prompt_lense/blob/main/extension/popup.js"
click node_extdash "https://github.com/skymahnoor/prompt_lense/blob/main/extension/dashboard.js"
click node_export "https://github.com/skymahnoor/prompt_lense/blob/main/extension/dashboard.js"
click node_webapp "https://github.com/skymahnoor/prompt_lense/blob/main/src/app/page.tsx"
click node_overview "https://github.com/skymahnoor/prompt_lense/blob/main/src/components/dashboard/overview.tsx"
click node_history "https://github.com/skymahnoor/prompt_lense/blob/main/src/components/dashboard/history.tsx"
click node_settings "https://github.com/skymahnoor/prompt_lense/blob/main/src/components/dashboard/settings-panel.tsx"
click node_eventsapi "https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/events/route.ts"
click node_statsapi "https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/stats/route.ts"
click node_seedapi "https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/seed/route.ts"
click node_healthapi "https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/health/route.ts"
click node_database "https://github.com/skymahnoor/prompt_lense/blob/main/src/lib/db.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content,node_engine,node_warning,node_eventlog,node_storage,node_background,node_user,node_webuser toneBlue
class node_popup,node_extdash,node_export toneAmber
class node_webapp,node_overview,node_history,node_settings toneMint
class node_eventsapi,node_statsapi,node_seedapi,node_healthapi,node_database toneRose
class node_ai toneIndigo
```

## Components

### Browser protection

- [Prompt interception](https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js): `extension/content.js`
- [PII detection and masking](https://github.com/skymahnoor/prompt_lense/blob/main/extension/lib/pii-engine.js): `extension/lib/pii-engine.js`
- [PII warning and choices](https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js): `extension/content.js`
- [Local interception history](https://github.com/skymahnoor/prompt_lense/blob/main/extension/content.js): `extension/content.js`
- **Chrome local storage**
- [Badge counter](https://github.com/skymahnoor/prompt_lense/blob/main/extension/background.js): `extension/background.js`

### Extension interface

- [Quick toggle and stats](https://github.com/skymahnoor/prompt_lense/blob/main/extension/popup.js): `extension/popup.js`
- [Extension dashboard](https://github.com/skymahnoor/prompt_lense/blob/main/extension/dashboard.js): `extension/dashboard.js`
- [JSON export and import](https://github.com/skymahnoor/prompt_lense/blob/main/extension/dashboard.js): `extension/dashboard.js`

### Optional web viewer

- [Viewer dashboard shell](https://github.com/skymahnoor/prompt_lense/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Analytics overview](https://github.com/skymahnoor/prompt_lense/blob/main/src/components/dashboard/overview.tsx): `src/components/dashboard/overview.tsx`
- [Searchable event history](https://github.com/skymahnoor/prompt_lense/blob/main/src/components/dashboard/history.tsx): `src/components/dashboard/history.tsx`
- [Import and settings](https://github.com/skymahnoor/prompt_lense/blob/main/src/components/dashboard/settings-panel.tsx): `src/components/dashboard/settings-panel.tsx`

### Viewer API and storage

- [Event API](https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/events/route.ts): `src/app/api/events/route.ts`
- [Statistics API](https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/stats/route.ts): `src/app/api/stats/route.ts`
- [Demo data API](https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/seed/route.ts): `src/app/api/seed/route.ts`
- [Health endpoint](https://github.com/skymahnoor/prompt_lense/blob/main/src/app/api/health/route.ts): `src/app/api/health/route.ts`
- [Viewer database](https://github.com/skymahnoor/prompt_lense/blob/main/src/lib/db.ts): `src/lib/db.ts`

### Other components

- **Prompt user**
- **AI chat site**
- **Viewer user**

## Connections

- Prompt user → Prompt interception: submits prompt (evidence: `README.md`)
- Prompt interception → PII detection and masking: detects and masks (evidence: `README.md`)
- Prompt interception → PII warning and choices: opens warning (evidence: `README.md`)
- PII warning and choices → AI chat site: sends masked prompt (evidence: `README.md`)
- PII warning and choices → Local interception history: records decision (evidence: `README.md`)
- Local interception history → Chrome local storage: stores locally (evidence: `README.md`)
- Badge counter → Chrome local storage: reads events (evidence: `README.md`)
- Quick toggle and stats → Chrome local storage: reads local stats (evidence: `README.md`)
- Extension dashboard → Chrome local storage: reads history (evidence: `README.md`)
- Extension dashboard → JSON export and import: exports and imports (evidence: `README.md`)
- Prompt user → Extension dashboard: reviews activity (evidence: `README.md`)
- Viewer user → Import and settings: chooses JSON file (evidence: `README.md`)
- Import and settings → Event API: imports events
- Viewer dashboard shell → Statistics API: fetches statistics (evidence: `src/app/page.tsx`)
- Viewer dashboard shell → Analytics overview: renders overview (evidence: `src/app/page.tsx`)
- Viewer dashboard shell → Searchable event history: renders history (evidence: `src/app/page.tsx`)
- Viewer dashboard shell → Import and settings: renders settings (evidence: `src/app/page.tsx`)
- Searchable event history → Event API: fetches events (evidence: `src/components/dashboard/history.tsx`)
- Event API → Viewer database: reads and writes (evidence: `src/app/api/events/route.ts`)
- Statistics API → Viewer database: reads events (evidence: `src/app/api/stats/route.ts`)
- Demo data API → Viewer database: creates demo events (evidence: `src/app/api/seed/route.ts`)
- Health endpoint → Viewer database
