# chris0jeky/navsentinel architecture

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

- Interactive diagram: https://gitdiagram.com/chris0jeky/navsentinel
- Repository: https://github.com/chris0jeky/navsentinel

## Overview

Heedline is a local-first Chrome extension that evaluates risky browser interactions and explains or intervenes on them. The main workflow runs from a page action through content-side detection and shared policy decisions, then to a prompt, block, or recorded outcome visible to the operator. Separate defenses cover navigation, credentials, double-click attacks, and clipboard traps; operator surfaces manage settings and review local history. The README also describes a Gym and an Observatory evidence workflow. Some wiring is documented rather than shown in the sampled excerpts, so uncertain links are omitted.

Main entry points: [`extension/src/shared/scoring.ts`](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/scoring.ts) (Risk scoring), [`extension/src/sw/sw.ts`](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/sw/sw.ts) (Service worker), [`extension/src/content/capture_isolated.ts`](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/capture_isolated.ts) (Action capture), [`extension/src/shared/storage_impl.ts`](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/storage_impl.ts) (Local state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Page defenses"]
  node_capture["Action capture"]
  node_navdefense["Navigation guards<br/>[main_guard.ts]"]
  node_credential["Credential checks"]
  node_doubleclick["Click correlation"]
  node_clickfix["Clipboard traps"]
end

subgraph group_decisions["Decision and state"]
  node_scoring["Risk scoring<br/>[scoring.ts]"]
  node_policy["Domain policy<br/>[domain_profile.ts]"]
  node_worker["Service worker<br/>[sw.ts]"]
  node_pending["Pending decisions"]
  node_storage[("Local state<br/>[storage_impl.ts]")]
end

subgraph group_operator["Operator surfaces"]
  node_prompt["Decision prompt"]
  node_popup["Popup<br/>[popup.ts]"]
  node_options["Settings<br/>[options.ts]"]
  node_evidence["Evidence records<br/>[evidence.ts]"]
end

subgraph group_evidence["Evidence workflow"]
  node_gym["Attack scenarios"]
  node_observatory["Scene recording"]
  node_reporter["Campaign reporting<br/>[reporter.mjs]"]
end

node_user(("Browser user"))
node_page["Web page"]
node_chrome["Chrome browser"]

node_user -->|"acts on"| node_page
node_page -->|"action context"| node_capture
node_capture -->|"checks navigation"| node_navdefense
node_capture -->|"checks submission"| node_credential
node_capture -->|"correlates clicks"| node_doubleclick
node_capture -->|"checks clipboard"| node_clickfix
node_navdefense -->|"evaluates risk"| node_scoring
node_credential -->|"evaluates risk"| node_scoring
node_doubleclick -->|"signals attack"| node_scoring
node_clickfix -->|"signals attack"| node_scoring
node_scoring -->|"applies policy"| node_policy
node_worker -->|"coordinates decisions"| node_scoring
node_worker -->|"manages prompts"| node_pending
node_pending -->|"stores decisions"| node_storage
node_worker -->|"records outcomes"| node_storage
node_worker -->|"updates badge"| node_chrome
node_pending -->|"delivers decision"| node_prompt
node_user -->|"reviews status"| node_popup
node_popup -->|"reads local state"| node_storage
node_user -->|"sets preferences"| node_options
node_options -->|"saves settings"| node_storage
node_worker -->|"records outcomes"| node_evidence
node_gym -.->|"serves fixtures"| node_page
node_observatory -.->|"captures scenes"| node_chrome
node_observatory -->|"produces receipts"| node_reporter

click node_capture "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/capture_isolated.ts"
click node_navdefense "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/main_guard.ts"
click node_credential "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/content_analyzer.ts"
click node_doubleclick "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/shadow_guard_correlation.ts"
click node_clickfix "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/clipboard_bridge.ts"
click node_scoring "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/scoring.ts"
click node_policy "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/domain_profile.ts"
click node_worker "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/sw/sw.ts"
click node_pending "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/sw/pending_decision_handlers.ts"
click node_storage "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/storage_impl.ts"
click node_prompt "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/smart_prompt_gate.ts"
click node_popup "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/popup/popup.ts"
click node_options "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/options/options.ts"
click node_evidence "https://github.com/chris0jeky/navsentinel/blob/main/extension/src/evidence/evidence.ts"
click node_gym "https://github.com/chris0jeky/navsentinel/tree/main/gym"
click node_observatory "https://github.com/chris0jeky/navsentinel/tree/main/experiments/evidence-observatory"
click node_reporter "https://github.com/chris0jeky/navsentinel/blob/main/experiments/evidence-observatory/reporter.mjs"

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_capture,node_navdefense,node_credential,node_doubleclick,node_clickfix,node_user,node_chrome toneBlue
class node_scoring,node_policy,node_worker,node_pending,node_storage toneAmber
class node_prompt,node_popup,node_options,node_evidence toneMint
class node_gym,node_observatory,node_reporter toneRose
class node_page toneIndigo
```

## Components

### Page defenses

- [Action capture](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/capture_isolated.ts): `extension/src/content/capture_isolated.ts`
- [Navigation guards](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/main_guard.ts): `extension/src/content/main_guard.ts`
- [Credential checks](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/content_analyzer.ts): `extension/src/content/content_analyzer.ts`
- [Click correlation](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/shadow_guard_correlation.ts): `extension/src/content/shadow_guard_correlation.ts`
- [Clipboard traps](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/clipboard_bridge.ts): `extension/src/content/clipboard_bridge.ts`

### Decision and state

- [Risk scoring](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/scoring.ts): `extension/src/shared/scoring.ts`
- [Domain policy](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/domain_profile.ts): `extension/src/shared/domain_profile.ts`
- [Service worker](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/sw/sw.ts): `extension/src/sw/sw.ts`
- [Pending decisions](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/sw/pending_decision_handlers.ts): `extension/src/sw/pending_decision_handlers.ts`
- [Local state](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/shared/storage_impl.ts): `extension/src/shared/storage_impl.ts`

### Operator surfaces

- [Decision prompt](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/content/smart_prompt_gate.ts): `extension/src/content/smart_prompt_gate.ts`
- [Popup](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/popup/popup.ts): `extension/src/popup/popup.ts`
- [Settings](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/options/options.ts): `extension/src/options/options.ts`
- [Evidence records](https://github.com/chris0jeky/navsentinel/blob/main/extension/src/evidence/evidence.ts): `extension/src/evidence/evidence.ts`

### Evidence workflow

- [Attack scenarios](https://github.com/chris0jeky/navsentinel/tree/main/gym): `gym`
- [Scene recording](https://github.com/chris0jeky/navsentinel/tree/main/experiments/evidence-observatory): `experiments/evidence-observatory`
- [Campaign reporting](https://github.com/chris0jeky/navsentinel/blob/main/experiments/evidence-observatory/reporter.mjs): `experiments/evidence-observatory/reporter.mjs`

### Other components

- **Browser user**
- **Web page**
- **Chrome browser**

## Connections

- Browser user → Web page: acts on
- Web page → Action capture: action context
- Action capture → Navigation guards: checks navigation
- Action capture → Credential checks: checks submission
- Action capture → Click correlation: correlates clicks
- Action capture → Clipboard traps: checks clipboard
- Navigation guards → Risk scoring: evaluates risk
- Credential checks → Risk scoring: evaluates risk
- Click correlation → Risk scoring: signals attack
- Clipboard traps → Risk scoring: signals attack
- Risk scoring → Domain policy: applies policy
- Service worker → Risk scoring: coordinates decisions
- Service worker → Pending decisions: manages prompts
- Pending decisions → Local state: stores decisions
- Service worker → Local state: records outcomes
- Service worker → Chrome browser: updates badge
- Pending decisions → Decision prompt: delivers decision
- Browser user → Popup: reviews status
- Popup → Local state: reads local state
- Browser user → Settings: sets preferences
- Settings → Local state: saves settings
- Service worker → Evidence records: records outcomes
- Attack scenarios → Web page: serves fixtures
- Scene recording → Chrome browser: captures scenes
- Scene recording → Campaign reporting: produces receipts