# creaofc/google-map-scrapper-kit architecture

> Architecture diagram of the GitHub repository creaofc/google-map-scrapper-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/creaofc/google-map-scrapper-kit
- Repository: https://github.com/creaofc/google-map-scrapper-kit

## Overview

Google Maps Scraper Kit is a local wrapper and set of interfaces for the upstream scraper, not the scraper engine itself. Users provide a business query and location; an interface geocodes it when needed, creates and polls a scraper job, downloads and cleans the results, and saves or displays a lead list. Optional website-based social enrichment is available in the Python CLI. The graph separates the documented Claude workflow, Python clients, and web interfaces. Some UI behavior is only partially excerpted; unsampled links are omitted or marked unverified.

Main entry points: [`scripts/scrape.py`](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py) (Python CLI), [`scripts/gui_server.py`](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py) (Dashboard Server), [`.claude/skills/google-maps-scraper/SKILL.md`](https://github.com/creaofc/google-map-scrapper-kit/blob/main/.claude/skills/google-maps-scraper/SKILL.md) (Scraper Skill), [`scripts/easy_scrape.py`](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/easy_scrape.py) (Easy CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_commands["Slash Commands<br/>[commands]"]
  node_skill["Scraper Skill<br/>[SKILL.md]"]
  node_python_cli["Python CLI<br/>[scrape.py]"]
  node_easy_cli["Easy CLI<br/>[easy_scrape.py]"]
  node_gui_page["Dashboard Page<br/>[gui.html]"]
  node_gui_server["Dashboard Server<br/>[gui_server.py]"]
  node_web_ui["Lead Scraper UI<br/>[ui_server.py]"]
end

subgraph group_jobs["Scrape Workflow"]
  node_geocoding["Location Geocoding<br/>[easy_scrape.py]"]
  node_job_client["Job API Client<br/>[scrape.py]"]
  node_dashboard_jobs["Dashboard Job Handler<br/>[gui_server.py]"]
  node_ui_proxy["UI API Proxy<br/>[ui_server.py]"]
end

subgraph group_results["Lead Results"]
  node_result_cleanup["Lead Cleanup<br/>[scrape.py]"]
  node_socials["Social Enrichment<br/>[scrape.py]"]
  node_lead_output["Lead Files"]
  node_dashboard_results["Dashboard Results<br/>[gui_server.py]"]
  node_ui_results["UI Results<br/>[ui_server.py]"]
end

subgraph group_external["External Services"]
  node_scraper_api{{"Upstream Scraper API"}}
  node_nominatim{{"Nominatim"}}
  node_business_sites{{"Business Websites"}}
end

node_user(("User"))
node_claude(("Claude Code"))

node_user -->|"runs query"| node_python_cli
node_user -->|"runs query"| node_easy_cli
node_user -->|"enters search"| node_gui_page
node_gui_page -.->|"sends requests"| node_gui_server
node_user -->|"uses interface"| node_web_ui
node_claude -->|"invokes"| node_skill
node_skill -.->|"uses workflow"| node_commands
node_skill -->|"drives jobs"| node_scraper_api
node_easy_cli -->|"geocodes location"| node_geocoding
node_geocoding -->|"queries"| node_nominatim
node_easy_cli -->|"creates and polls"| node_scraper_api
node_python_cli -->|"geocodes location"| node_nominatim
node_python_cli -->|"creates and polls"| node_scraper_api
node_python_cli -->|"selects fields"| node_result_cleanup
node_python_cli -->|"optionally enriches"| node_socials
node_socials -->|"fetches pages"| node_business_sites
node_result_cleanup -->|"writes CSV or JSON"| node_lead_output
node_socials -->|"adds social fields"| node_lead_output
node_gui_server -->|"serves page"| node_gui_page
node_gui_server -->|"geocodes location"| node_nominatim
node_gui_server -->|"creates and checks jobs"| node_scraper_api
node_gui_server -->|"returns cleaned rows"| node_dashboard_results
node_web_ui -->|"sends requests"| node_ui_proxy
node_ui_proxy -->|"geocodes location"| node_nominatim
node_ui_proxy -->|"proxies job requests"| node_scraper_api
node_web_ui -.->|"renders and exports"| node_ui_results

click node_commands "https://github.com/creaofc/google-map-scrapper-kit/tree/main/.claude/commands"
click node_skill "https://github.com/creaofc/google-map-scrapper-kit/blob/main/.claude/skills/google-maps-scraper/SKILL.md"
click node_python_cli "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py"
click node_easy_cli "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/easy_scrape.py"
click node_gui_page "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui.html"
click node_gui_server "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py"
click node_web_ui "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/ui_server.py"
click node_geocoding "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/easy_scrape.py"
click node_job_client "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py"
click node_dashboard_jobs "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py"
click node_ui_proxy "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/ui_server.py"
click node_result_cleanup "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py"
click node_socials "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py"
click node_dashboard_results "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py"
click node_ui_results "https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/ui_server.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_commands,node_skill,node_python_cli,node_easy_cli,node_gui_page,node_gui_server,node_web_ui,node_user toneBlue
class node_geocoding,node_job_client,node_dashboard_jobs,node_ui_proxy toneAmber
class node_result_cleanup,node_socials,node_lead_output,node_dashboard_results,node_ui_results toneMint
class node_scraper_api,node_nominatim,node_business_sites toneRose
class node_claude toneIndigo
```

## Components

### User Interfaces

- [Slash Commands](https://github.com/creaofc/google-map-scrapper-kit/tree/main/.claude/commands): `.claude/commands`
- [Scraper Skill](https://github.com/creaofc/google-map-scrapper-kit/blob/main/.claude/skills/google-maps-scraper/SKILL.md): `.claude/skills/google-maps-scraper/SKILL.md`
- [Python CLI](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py): `scripts/scrape.py`
- [Easy CLI](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/easy_scrape.py): `scripts/easy_scrape.py`
- [Dashboard Page](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui.html): `scripts/gui.html`
- [Dashboard Server](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py): `scripts/gui_server.py`
- [Lead Scraper UI](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/ui_server.py): `scripts/ui_server.py`

### Scrape Workflow

- [Location Geocoding](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/easy_scrape.py): `scripts/easy_scrape.py`
- [Job API Client](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py): `scripts/scrape.py`
- [Dashboard Job Handler](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py): `scripts/gui_server.py`
- [UI API Proxy](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/ui_server.py): `scripts/ui_server.py`

### Lead Results

- [Lead Cleanup](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py): `scripts/scrape.py`
- [Social Enrichment](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/scrape.py): `scripts/scrape.py`
- **Lead Files**
- [Dashboard Results](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/gui_server.py): `scripts/gui_server.py`
- [UI Results](https://github.com/creaofc/google-map-scrapper-kit/blob/main/scripts/ui_server.py): `scripts/ui_server.py`

### External Services

- **Upstream Scraper API**
- **Nominatim**
- **Business Websites**

### Other components

- **User**
- **Claude Code**

## Connections

- User → Python CLI: runs query (evidence: `README.md`)
- User → Easy CLI: runs query (evidence: `README.md`)
- User → Dashboard Page: enters search (evidence: `README.md`)
- Dashboard Page → Dashboard Server: sends requests
- User → Lead Scraper UI: uses interface (evidence: `README.md`)
- Claude Code → Scraper Skill: invokes (evidence: `README.md`)
- Scraper Skill → Slash Commands: uses workflow
- Scraper Skill → Upstream Scraper API: drives jobs (evidence: `README.md`)
- Easy CLI → Location Geocoding: geocodes location (evidence: `scripts/easy_scrape.py`)
- Location Geocoding → Nominatim: queries (evidence: `scripts/easy_scrape.py`)
- Easy CLI → Upstream Scraper API: creates and polls (evidence: `scripts/easy_scrape.py`)
- Python CLI → Nominatim: geocodes location (evidence: `scripts/scrape.py`)
- Python CLI → Upstream Scraper API: creates and polls (evidence: `scripts/scrape.py`)
- Python CLI → Lead Cleanup: selects fields (evidence: `scripts/scrape.py`)
- Python CLI → Social Enrichment: optionally enriches (evidence: `scripts/scrape.py`)
- Social Enrichment → Business Websites: fetches pages (evidence: `scripts/scrape.py`)
- Lead Cleanup → Lead Files: writes CSV or JSON (evidence: `scripts/scrape.py`)
- Social Enrichment → Lead Files: adds social fields (evidence: `scripts/scrape.py`)
- Dashboard Server → Dashboard Page: serves page (evidence: `scripts/gui_server.py`)
- Dashboard Server → Nominatim: geocodes location (evidence: `scripts/gui_server.py`)
- Dashboard Server → Upstream Scraper API: creates and checks jobs (evidence: `scripts/gui_server.py`)
- Dashboard Server → Dashboard Results: returns cleaned rows (evidence: `scripts/gui_server.py`)
- Lead Scraper UI → UI API Proxy: sends requests (evidence: `scripts/ui_server.py`)
- UI API Proxy → Nominatim: geocodes location (evidence: `scripts/ui_server.py`)
- UI API Proxy → Upstream Scraper API: proxies job requests (evidence: `scripts/ui_server.py`)
- Lead Scraper UI → UI Results: renders and exports (evidence: `scripts/ui_server.py`)
