# kartikvermagit-ds/nudgekavach architecture

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

- Interactive diagram: https://gitdiagram.com/kartikvermagit-ds/nudgekavach
- Repository: https://github.com/kartikvermagit-ds/nudgekavach

## Overview

NudgeKavach is a local-first Chrome extension for observing possible dark patterns and presenting NudgeProof evidence, alongside a controlled demo store and comparison mode. The main workflow is: a user opens a page and starts or receives monitoring; the content script observes page changes, applies deterministic rules, retains findings and timeline events in tab memory, and presents an on-page panel with highlights and JSON export. The local server only hosts the demo frontend. The README documents the five detector types and other panel capabilities; omitted source excerpts limit certainty about some internal UI wiring.

Main entry points: [`extension/content.js`](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js) (Page observer), [`backend/server.cjs`](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/backend/server.cjs) (Demo HTTP server), [`extension/popup.js`](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/popup.js) (Scan activation), [`frontend/store.js`](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/store.js) (Store and comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Demo frontend"]
  node_store["Store and comparison<br/>[store.js]"]
  node_store_page["Store page<br/>[index.html]"]
  node_guide["Presenter guide<br/>[guide.html]"]
end

subgraph group_hosting["Local hosting"]
  node_server["Demo HTTP server<br/>[server.cjs]"]
end

subgraph group_extension["Browser extension"]
  node_popup_ui["Toolbar popup<br/>[popup.html]"]
  node_popup["Scan activation<br/>[popup.js]"]
  node_observer["Page observer<br/>[content.js]"]
  node_rules["Deterministic detectors<br/>[rules.js]"]
end

subgraph group_evidence["Evidence experience"]
  node_session["Findings and timeline<br/>[content.js]"]
  node_panel["Evidence panel<br/>[content.js]"]
  node_export["NudgeProof JSON<br/>[content.js]"]
end

node_user(("User"))
node_browser(("Chrome browser"))
node_target_page["Open page"]

node_user -->|"opens page"| node_browser
node_browser -->|"requests demo"| node_server
node_server -->|"serves frontend"| node_store_page
node_server -->|"serves frontend"| node_guide
node_store_page -->|"loads script"| node_store
node_store -->|"updates demo DOM"| node_target_page
node_user -->|"starts scan"| node_popup_ui
node_popup_ui -->|"invokes scan"| node_popup
node_popup -->|"queries active tab"| node_browser
node_popup -->|"injects scripts"| node_observer
node_observer -->|"observes DOM"| node_target_page
node_observer -->|"evaluates observations"| node_rules
node_observer -->|"records evidence"| node_session
node_session -->|"renders findings"| node_panel
node_user -->|"controls monitoring"| node_panel
node_panel -->|"exports report"| node_export
node_user -->|"downloads report"| node_export

click node_store "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/store.js"
click node_store_page "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/index.html"
click node_guide "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/guide.html"
click node_server "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/backend/server.cjs"
click node_popup_ui "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/popup.html"
click node_popup "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/popup.js"
click node_observer "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js"
click node_rules "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/rules.js"
click node_session "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js"
click node_panel "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js"
click node_export "https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js"

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_store,node_store_page,node_guide,node_user,node_browser toneBlue
class node_server toneAmber
class node_popup_ui,node_popup,node_observer,node_rules toneMint
class node_session,node_panel,node_export toneRose
class node_target_page toneIndigo
```

## Components

### Demo frontend

- [Store and comparison](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/store.js): `frontend/store.js`
- [Store page](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/index.html): `frontend/index.html`
- [Presenter guide](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/frontend/guide.html): `frontend/guide.html`

### Local hosting

- [Demo HTTP server](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/backend/server.cjs): `backend/server.cjs`

### Browser extension

- [Toolbar popup](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/popup.html): `extension/popup.html`
- [Scan activation](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/popup.js): `extension/popup.js`
- [Page observer](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js): `extension/content.js`
- [Deterministic detectors](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/rules.js): `extension/rules.js`

### Evidence experience

- [Findings and timeline](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js): `extension/content.js`
- [Evidence panel](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js): `extension/content.js`
- [NudgeProof JSON](https://github.com/kartikvermagit-ds/nudgekavach/blob/main/extension/content.js): `extension/content.js`

### Other components

- **User**
- **Chrome browser**
- **Open page**

## Connections

- User → Chrome browser: opens page
- Chrome browser → Demo HTTP server: requests demo
- Demo HTTP server → Store page: serves frontend
- Demo HTTP server → Presenter guide: serves frontend
- Store page → Store and comparison: loads script
- Store and comparison → Open page: updates demo DOM
- User → Toolbar popup: starts scan
- Toolbar popup → Scan activation: invokes scan
- Scan activation → Chrome browser: queries active tab
- Scan activation → Page observer: injects scripts
- Page observer → Open page: observes DOM
- Page observer → Deterministic detectors: evaluates observations
- Page observer → Findings and timeline: records evidence
- Findings and timeline → Evidence panel: renders findings
- User → Evidence panel: controls monitoring
- Evidence panel → NudgeProof JSON: exports report
- User → NudgeProof JSON: downloads report