# tuhin-thinks/snifferex architecture

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

- Interactive diagram: https://gitdiagram.com/tuhin-thinks/snifferex
- Repository: https://github.com/tuhin-thinks/snifferex

## Overview

SnifferEx pairs a browser extension with Python WebSocket consumers to scrape live pages and send browser actions over the same session. The main flow is: a user starts listening, the extension connects, a consumer submits extraction or action commands, and results return to that consumer. The README also describes real-user/hybrid use and dynamic-page support. The deployment diagram mentions message buses and workers, but the sampled runtime shows a local WebSocket server instead; those documented future-style services are not mapped here. Some server and extension excerpts are partial, so uncertain internal links are omitted.

Main entry points: [`extension/background.js`](https://github.com/tuhin-thinks/snifferex/blob/master/extension/background.js) (Socket and command handler), [`Websocket_Server_AND_Consumer/ws_server.py`](https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/ws_server.py) (WebSocket server), [`Websocket_Server_AND_Consumer/example_consumers`](https://github.com/tuhin-thinks/snifferex/tree/master/Websocket_Server_AND_Consumer/example_consumers) (Scraping consumers), [`extension/popup.js`](https://github.com/tuhin-thinks/snifferex/blob/master/extension/popup.js) (Extension popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser extension"]
  node_popup["Extension popup<br/>[popup.js]"]
  node_background["Socket and command handler<br/>[background.js]"]
  node_page_extraction["Page extraction script<br/>[content.js]"]
end

subgraph group_gateway["WebSocket backend"]
  node_server["WebSocket server<br/>[ws_server.py]"]
  node_connection["Connection state"]
end

subgraph group_consumers["Consumer clients"]
  node_consumer_examples["Scraping consumers"]
  node_consumer_output["Scraped results"]
end

node_user(("Browser user"))
node_page["Active webpage"]

node_user -->|"starts listening"| node_popup
node_popup -->|"requests socket"| node_background
node_background -->|"opens WebSocket"| node_server
node_server -->|"uses connections"| node_connection
node_consumer_examples -->|"sends commands"| node_server
node_server -->|"routes commands"| node_background
node_background -->|"extracts or acts"| node_page
node_page -->|"returns extraction"| node_background
node_server -->|"forwards results"| node_consumer_examples
node_consumer_examples -->|"writes results"| node_consumer_output
node_background -.->|"may delegate"| node_page_extraction

click node_popup "https://github.com/tuhin-thinks/snifferex/blob/master/extension/popup.js"
click node_background "https://github.com/tuhin-thinks/snifferex/blob/master/extension/background.js"
click node_page_extraction "https://github.com/tuhin-thinks/snifferex/blob/master/extension/content.js"
click node_server "https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/ws_server.py"
click node_connection "https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/connection_handler.py"
click node_consumer_examples "https://github.com/tuhin-thinks/snifferex/tree/master/Websocket_Server_AND_Consumer/example_consumers"
click node_consumer_output "https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/example_consumers/ex_insta_follower_users.py"

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_popup,node_background,node_page_extraction,node_user toneBlue
class node_server,node_connection toneAmber
class node_consumer_examples,node_consumer_output toneMint
class node_page toneIndigo
```

## Components

### Browser extension

- [Extension popup](https://github.com/tuhin-thinks/snifferex/blob/master/extension/popup.js): `extension/popup.js`
- [Socket and command handler](https://github.com/tuhin-thinks/snifferex/blob/master/extension/background.js): `extension/background.js`
- [Page extraction script](https://github.com/tuhin-thinks/snifferex/blob/master/extension/content.js): `extension/content.js`

### WebSocket backend

- [WebSocket server](https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/ws_server.py): `Websocket_Server_AND_Consumer/ws_server.py`
- [Connection state](https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/connection_handler.py): `Websocket_Server_AND_Consumer/connection_handler.py`

### Consumer clients

- [Scraping consumers](https://github.com/tuhin-thinks/snifferex/tree/master/Websocket_Server_AND_Consumer/example_consumers): `Websocket_Server_AND_Consumer/example_consumers`
- [Scraped results](https://github.com/tuhin-thinks/snifferex/blob/master/Websocket_Server_AND_Consumer/example_consumers/ex_insta_follower_users.py): `Websocket_Server_AND_Consumer/example_consumers/ex_insta_follower_users.py`

### Other components

- **Browser user**
- **Active webpage**

## Connections

- Browser user → Extension popup: starts listening (evidence: `extension/popup.js`)
- Extension popup → Socket and command handler: requests socket (evidence: `extension/popup.js`)
- Socket and command handler → WebSocket server: opens WebSocket (evidence: `extension/background.js`)
- WebSocket server → Connection state: uses connections (evidence: `Websocket_Server_AND_Consumer/ws_server.py`)
- Scraping consumers → WebSocket server: sends commands (evidence: `Websocket_Server_AND_Consumer/example_consumers/ex_linkedin_post_text_preview.py`)
- WebSocket server → Socket and command handler: routes commands (evidence: `README.md`)
- Socket and command handler → Active webpage: extracts or acts (evidence: `extension/background.js`)
- Active webpage → Socket and command handler: returns extraction (evidence: `extension/background.js`)
- WebSocket server → Scraping consumers: forwards results (evidence: `README.md`)
- Scraping consumers → Scraped results: writes results (evidence: `Websocket_Server_AND_Consumer/example_consumers/ex_insta_follower_users.py`)
- Socket and command handler → Page extraction script: may delegate
