# hackunderway/searchphone architecture

> Architecture diagram of the GitHub repository hackunderway/searchphone, 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/hackunderway/searchphone
- Repository: https://github.com/hackunderway/searchphone

## Overview

SearchPhone is a terminal OSINT tool that takes a phone number, validates and enriches it, searches several public and commercial sources, and presents findings in the terminal and automatic JSON/PDF reports. The README documents the major search capabilities and parallel execution; the excerpt shows a single PhoneOSINT implementation and result structure. Distinct feature nodes share that source path because the repository has no separate runtime modules. Some orchestration details and report wiring are not visible in the excerpt, so those links rely on README statements.

Main entry points: [`search_phone.py`](https://github.com/hackunderway/searchphone/blob/main/search_phone.py) (CLI analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Analysis workflow"]
  node_cli["CLI analysis<br/>[search_phone.py]"]
  node_validation["Number validation<br/>[search_phone.py]"]
end

subgraph group_sources["Intelligence sources"]
  node_carrier["Carrier lookup<br/>[search_phone.py]"]
  node_google["Google search<br/>[search_phone.py]"]
  node_duckduckgo["DuckDuckGo search<br/>[search_phone.py]"]
  node_github["GitHub search<br/>[search_phone.py]"]
  node_reddit["Reddit search<br/>[search_phone.py]"]
  node_hudson["Infostealer check<br/>[search_phone.py]"]
end

subgraph group_results["Results and reporting"]
  node_result_state["Collected results<br/>[search_phone.py]"]
  node_terminal_output["Terminal output<br/>[search_phone.py]"]
  node_json_report["JSON report<br/>[search_phone.py]"]
  node_pdf_report["PDF report<br/>[search_phone.py]"]
end

node_user(("Terminal user"))
node_serpapi["SerpAPI"]
node_numverify["Numverify"]
node_github_api["GitHub API"]
node_hudson_api["Hudson Rock API"]
node_reddit_service["Reddit"]
node_search_results["Search engines"]

node_user -->|"submits number"| node_cli
node_cli -.->|"validates"| node_validation
node_cli -.->|"looks up carrier"| node_carrier
node_cli -->|"searches"| node_google
node_cli -->|"searches"| node_duckduckgo
node_cli -->|"searches"| node_github
node_cli -->|"searches"| node_reddit
node_cli -->|"checks exposure"| node_hudson
node_google -->|"queries"| node_serpapi
node_google -->|"uses"| node_search_results
node_duckduckgo -->|"uses"| node_search_results
node_carrier -->|"queries"| node_numverify
node_github -->|"searches code"| node_github_api
node_reddit -->|"searches mentions"| node_reddit_service
node_hudson -->|"checks number"| node_hudson_api
node_cli -.->|"collects findings"| node_result_state
node_result_state -.->|"renders"| node_terminal_output
node_result_state -->|"generates"| node_json_report
node_result_state -->|"generates"| node_pdf_report
node_cli -->|"runs in parallel"| node_google
node_cli -->|"runs in parallel"| node_duckduckgo
node_cli -->|"runs in parallel"| node_github
node_cli -->|"runs in parallel"| node_reddit

click node_cli "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_validation "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_carrier "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_google "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_duckduckgo "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_github "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_reddit "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_hudson "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_result_state "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_terminal_output "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_json_report "https://github.com/hackunderway/searchphone/blob/main/search_phone.py"
click node_pdf_report "https://github.com/hackunderway/searchphone/blob/main/search_phone.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_cli,node_validation,node_user toneBlue
class node_carrier,node_google,node_duckduckgo,node_github,node_reddit,node_hudson toneAmber
class node_result_state,node_terminal_output,node_json_report,node_pdf_report,node_serpapi,node_github_api,node_hudson_api toneMint
class node_numverify,node_reddit_service,node_search_results toneIndigo
```

## Components

### Analysis workflow

- [CLI analysis](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [Number validation](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`

### Intelligence sources

- [Carrier lookup](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [Google search](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [DuckDuckGo search](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [GitHub search](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [Reddit search](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [Infostealer check](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`

### Results and reporting

- [Collected results](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [Terminal output](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [JSON report](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`
- [PDF report](https://github.com/hackunderway/searchphone/blob/main/search_phone.py): `search_phone.py`

### Other components

- **Terminal user**
- **SerpAPI**
- **Numverify**
- **GitHub API**
- **Hudson Rock API**
- **Reddit**
- **Search engines**

## Connections

- Terminal user → CLI analysis: submits number (evidence: `README.md`)
- CLI analysis → Number validation: validates (evidence: `search_phone.py`)
- CLI analysis → Carrier lookup: looks up carrier (evidence: `search_phone.py`)
- CLI analysis → Google search: searches (evidence: `README.md`)
- CLI analysis → DuckDuckGo search: searches (evidence: `README.md`)
- CLI analysis → GitHub search: searches (evidence: `README.md`)
- CLI analysis → Reddit search: searches (evidence: `README.md`)
- CLI analysis → Infostealer check: checks exposure (evidence: `README.md`)
- Google search → SerpAPI: queries (evidence: `README.md`)
- Google search → Search engines: uses (evidence: `README.md`)
- DuckDuckGo search → Search engines: uses (evidence: `README.md`)
- Carrier lookup → Numverify: queries (evidence: `README.md`)
- GitHub search → GitHub API: searches code (evidence: `README.md`)
- Reddit search → Reddit: searches mentions (evidence: `README.md`)
- Infostealer check → Hudson Rock API: checks number (evidence: `README.md`)
- CLI analysis → Collected results: collects findings (evidence: `search_phone.py`)
- Collected results → Terminal output: renders (evidence: `search_phone.py`)
- Collected results → JSON report: generates (evidence: `README.md`)
- Collected results → PDF report: generates (evidence: `README.md`)
- CLI analysis → Google search: runs in parallel (evidence: `README.md`)
- CLI analysis → DuckDuckGo search: runs in parallel (evidence: `README.md`)
- CLI analysis → GitHub search: runs in parallel (evidence: `README.md`)
- CLI analysis → Reddit search: runs in parallel (evidence: `README.md`)
