# thewhiteh4t/seeker architecture

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

- Interactive diagram: https://gitdiagram.com/thewhiteh4t/seeker
- Repository: https://github.com/thewhiteh4t/seeker

## Overview

Seeker is a Python-driven web tool that configures and serves a selected page template, then processes browser-submitted device, location, and IP information for display, export, and optional notifications. The README documents the collection capabilities and template choices; excerpts show template selection, PHP server startup, IP reconnaissance, and notification dispatch. Some browser-to-PHP wiring and handler behavior is not shown, so those links are marked unverified or omitted.

Main entry points: [`seeker.py`](https://github.com/thewhiteh4t/seeker/blob/master/seeker.py) (CLI and orchestrator), [`template`](https://github.com/thewhiteh4t/seeker/tree/master/template) (Template setup modules), [`js/location.js`](https://github.com/thewhiteh4t/seeker/blob/master/js/location.js) (Browser location capture), [`template/captcha/js/main_temp.js`](https://github.com/thewhiteh4t/seeker/blob/master/template/captcha/js/main_temp.js) (Device fingerprinting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Runtime control"]
  node_seeker["CLI and orchestrator<br/>[seeker.py]"]
  node_phpserver["PHP page server<br/>[seeker.py]"]
end

subgraph group_pages["Page templates"]
  node_template_catalog["Template catalog<br/>[templates.json]"]
  node_template_setup["Template setup modules"]
  node_page_assets["Template page assets"]
end

subgraph group_collection["Data collection"]
  node_location_capture["Browser location capture<br/>[location.js]"]
  node_device_capture["Device fingerprinting<br/>[main_temp.js]"]
  node_info_handler["Device info handler<br/>[info.php]"]
  node_result_handler["Location result handler<br/>[result.php]"]
  node_error_handler["Error handler<br/>[error.php]"]
  node_ip_recon["IP reconnaissance<br/>[seeker.py]"]
end

subgraph group_outputs["Results and delivery"]
  node_csv_output["CSV output<br/>[seeker.py]"]
  node_kml_output["KML export<br/>[seeker.py]"]
  node_telegram_delivery["Telegram delivery<br/>[telegram_api.py]"]
  node_discord_delivery["Discord delivery<br/>[discord_webhook.py]"]
end

node_operator(("Operator"))
node_visitor(("Page visitor"))
node_webhook(("Webhook endpoint"))
node_telegram_service(("Telegram service"))
node_discord_service(("Discord service"))
node_ipwhois(("IP lookup service"))

node_operator -->|"configures"| node_seeker
node_seeker -.->|"selects template"| node_template_catalog
node_seeker -->|"imports setup"| node_template_setup
node_template_setup -->|"generates pages"| node_page_assets
node_seeker -->|"starts server"| node_phpserver
node_phpserver -.->|"serves page"| node_visitor
node_visitor -->|"grants location"| node_location_capture
node_visitor -.->|"opens page"| node_device_capture
node_location_capture -.->|"submits coordinates"| node_result_handler
node_device_capture -.->|"submits device data"| node_info_handler
node_phpserver -.->|"serves handler"| node_error_handler
node_seeker -->|"looks up IP"| node_ip_recon
node_ip_recon -->|"queries"| node_ipwhois
node_seeker -->|"writes results"| node_csv_output
node_seeker -->|"exports coordinates"| node_kml_output
node_seeker -->|"dispatches messages"| node_telegram_delivery
node_telegram_delivery -->|"sends messages"| node_telegram_service
node_seeker -->|"dispatches Discord"| node_discord_delivery
node_discord_delivery -->|"posts embeds"| node_discord_service
node_seeker -->|"posts events"| node_webhook

click node_seeker "https://github.com/thewhiteh4t/seeker/blob/master/seeker.py"
click node_phpserver "https://github.com/thewhiteh4t/seeker/blob/master/seeker.py"
click node_template_catalog "https://github.com/thewhiteh4t/seeker/blob/master/template/templates.json"
click node_template_setup "https://github.com/thewhiteh4t/seeker/tree/master/template"
click node_page_assets "https://github.com/thewhiteh4t/seeker/tree/master/template"
click node_location_capture "https://github.com/thewhiteh4t/seeker/blob/master/js/location.js"
click node_device_capture "https://github.com/thewhiteh4t/seeker/blob/master/template/captcha/js/main_temp.js"
click node_info_handler "https://github.com/thewhiteh4t/seeker/blob/master/php/info.php"
click node_result_handler "https://github.com/thewhiteh4t/seeker/blob/master/php/result.php"
click node_error_handler "https://github.com/thewhiteh4t/seeker/blob/master/php/error.php"
click node_ip_recon "https://github.com/thewhiteh4t/seeker/blob/master/seeker.py"
click node_csv_output "https://github.com/thewhiteh4t/seeker/blob/master/seeker.py"
click node_kml_output "https://github.com/thewhiteh4t/seeker/blob/master/seeker.py"
click node_telegram_delivery "https://github.com/thewhiteh4t/seeker/blob/master/telegram_api.py"
click node_discord_delivery "https://github.com/thewhiteh4t/seeker/blob/master/discord_webhook.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_seeker,node_phpserver toneBlue
class node_template_catalog,node_template_setup,node_page_assets toneAmber
class node_location_capture,node_device_capture,node_info_handler,node_result_handler,node_error_handler,node_ip_recon,node_webhook toneMint
class node_csv_output,node_kml_output,node_telegram_delivery,node_discord_delivery toneRose
class node_operator,node_visitor,node_telegram_service,node_discord_service,node_ipwhois toneIndigo
```

## Components

### Runtime control

- [CLI and orchestrator](https://github.com/thewhiteh4t/seeker/blob/master/seeker.py): `seeker.py`
- [PHP page server](https://github.com/thewhiteh4t/seeker/blob/master/seeker.py): `seeker.py`

### Page templates

- [Template catalog](https://github.com/thewhiteh4t/seeker/blob/master/template/templates.json): `template/templates.json`
- [Template setup modules](https://github.com/thewhiteh4t/seeker/tree/master/template): `template`
- [Template page assets](https://github.com/thewhiteh4t/seeker/tree/master/template): `template`

### Data collection

- [Browser location capture](https://github.com/thewhiteh4t/seeker/blob/master/js/location.js): `js/location.js`
- [Device fingerprinting](https://github.com/thewhiteh4t/seeker/blob/master/template/captcha/js/main_temp.js): `template/captcha/js/main_temp.js`
- [Device info handler](https://github.com/thewhiteh4t/seeker/blob/master/php/info.php): `php/info.php`
- [Location result handler](https://github.com/thewhiteh4t/seeker/blob/master/php/result.php): `php/result.php`
- [Error handler](https://github.com/thewhiteh4t/seeker/blob/master/php/error.php): `php/error.php`
- [IP reconnaissance](https://github.com/thewhiteh4t/seeker/blob/master/seeker.py): `seeker.py`

### Results and delivery

- [CSV output](https://github.com/thewhiteh4t/seeker/blob/master/seeker.py): `seeker.py`
- [KML export](https://github.com/thewhiteh4t/seeker/blob/master/seeker.py): `seeker.py`
- [Telegram delivery](https://github.com/thewhiteh4t/seeker/blob/master/telegram_api.py): `telegram_api.py`
- [Discord delivery](https://github.com/thewhiteh4t/seeker/blob/master/discord_webhook.py): `discord_webhook.py`

### Other components

- **Operator**
- **Page visitor**
- **Webhook endpoint**
- **Telegram service**
- **Discord service**
- **IP lookup service**

## Connections

- Operator → CLI and orchestrator: configures (evidence: `README.md`)
- CLI and orchestrator → Template catalog: selects template
- CLI and orchestrator → Template setup modules: imports setup (evidence: `seeker.py`)
- Template setup modules → Template page assets: generates pages (evidence: `template/mod_telegram.py`)
- CLI and orchestrator → PHP page server: starts server (evidence: `seeker.py`)
- PHP page server → Page visitor: serves page
- Page visitor → Browser location capture: grants location (evidence: `README.md`)
- Page visitor → Device fingerprinting: opens page
- Browser location capture → Location result handler: submits coordinates
- Device fingerprinting → Device info handler: submits device data
- PHP page server → Error handler: serves handler
- CLI and orchestrator → IP reconnaissance: looks up IP (evidence: `seeker.py`)
- IP reconnaissance → IP lookup service: queries (evidence: `seeker.py`)
- CLI and orchestrator → CSV output: writes results (evidence: `seeker.py`)
- CLI and orchestrator → KML export: exports coordinates (evidence: `seeker.py`)
- CLI and orchestrator → Telegram delivery: dispatches messages (evidence: `seeker.py`)
- Telegram delivery → Telegram service: sends messages (evidence: `telegram_api.py`)
- CLI and orchestrator → Discord delivery: dispatches Discord (evidence: `seeker.py`)
- Discord delivery → Discord service: posts embeds (evidence: `discord_webhook.py`)
- CLI and orchestrator → Webhook endpoint: posts events (evidence: `seeker.py`)
