# oyekamal/maps2whatsapp architecture

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

## Overview

maps2whatsapp is a local web app for finding Google Maps businesses and sending them personalized WhatsApp outreach. The main workflow is search leads, draft and personalize editable messages, connect a WhatsApp account by QR code, then send selected messages with safeguards. The graph also shows CSV export and live status updates. Relationships are based on the README and sampled source; the UI implementation itself was not sampled, so its interactions are documented at the product level.

Main entry points: [`server.js`](https://github.com/oyekamal/maps2whatsapp/blob/master/server.js) (HTTP server), [`lib/whatsapp.js`](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js) (WhatsApp connection), [`lib/llm.js`](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/llm.js) (Message drafting), [`lib/scraper.js`](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/scraper.js) (Lead search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_ui["Web interface<br/>[index.html]"]
  node_server["HTTP server<br/>[server.js]"]
  node_live["Live updates<br/>[server.js]"]
end

subgraph group_leads["Lead discovery"]
  node_leadsearch["Lead search<br/>[scraper.js]"]
  node_geocode["Location geocoding<br/>[scraper.js]"]
  node_leaddata[("Lead results<br/>[server.js]")]
  node_csv["CSV export<br/>[util.js]"]
end

subgraph group_messages["Message drafting"]
  node_draft["Message drafting<br/>[llm.js]"]
  node_util["Lead and message utilities<br/>[util.js]"]
end

subgraph group_outreach["WhatsApp outreach"]
  node_whatsapp["WhatsApp connection<br/>[whatsapp.js]"]
  node_auth[("WhatsApp session<br/>[whatsapp.js]")]
  node_sendjob["Send job<br/>[server.js]"]
  node_sentlog[("Sent history<br/>[whatsapp.js]")]
end

node_user(("Freelancer"))
node_osm["OpenStreetMap Nominatim"]
node_maps["Google Maps scraper"]
node_ollama["Ollama"]
node_waweb["WhatsApp Web"]

node_user -->|"uses"| node_ui
node_ui -->|"requests actions"| node_server
node_server -->|"searches leads"| node_leadsearch
node_leadsearch -->|"geocodes location"| node_geocode
node_geocode -->|"queries"| node_osm
node_leadsearch -->|"runs query"| node_maps
node_server -->|"stores results"| node_leaddata
node_server -->|"exports leads"| node_csv
node_server -->|"drafts message"| node_draft
node_server -->|"personalizes leads"| node_draft
node_draft -->|"generates text"| node_ollama
node_draft -->|"renders fallback"| node_util
node_server -->|"connects account"| node_whatsapp
node_whatsapp -->|"connects and sends"| node_waweb
node_whatsapp -->|"saves session"| node_auth
node_server -->|"starts send job"| node_sendjob
node_sendjob -->|"sends messages"| node_whatsapp
node_sendjob -->|"renders template"| node_util
node_whatsapp -->|"records sends"| node_sentlog
node_server -->|"emits events"| node_live
node_live -->|"streams status"| node_ui

click node_ui "https://github.com/oyekamal/maps2whatsapp/blob/master/public/index.html"
click node_server "https://github.com/oyekamal/maps2whatsapp/blob/master/server.js"
click node_live "https://github.com/oyekamal/maps2whatsapp/blob/master/server.js"
click node_leadsearch "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/scraper.js"
click node_geocode "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/scraper.js"
click node_leaddata "https://github.com/oyekamal/maps2whatsapp/blob/master/server.js"
click node_csv "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/util.js"
click node_draft "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/llm.js"
click node_whatsapp "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js"
click node_auth "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js"
click node_sendjob "https://github.com/oyekamal/maps2whatsapp/blob/master/server.js"
click node_sentlog "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js"
click node_util "https://github.com/oyekamal/maps2whatsapp/blob/master/lib/util.js"

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_ui,node_server,node_live toneBlue
class node_leadsearch,node_geocode,node_leaddata,node_csv toneAmber
class node_draft,node_util toneMint
class node_whatsapp,node_auth,node_sendjob,node_sentlog toneRose
class node_user,node_osm,node_maps,node_ollama,node_waweb toneIndigo
```

## Components

### Web app

- [Web interface](https://github.com/oyekamal/maps2whatsapp/blob/master/public/index.html): `public/index.html`
- [HTTP server](https://github.com/oyekamal/maps2whatsapp/blob/master/server.js): `server.js`
- [Live updates](https://github.com/oyekamal/maps2whatsapp/blob/master/server.js): `server.js`

### Lead discovery

- [Lead search](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/scraper.js): `lib/scraper.js`
- [Location geocoding](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/scraper.js): `lib/scraper.js`
- [Lead results](https://github.com/oyekamal/maps2whatsapp/blob/master/server.js): `server.js`
- [CSV export](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/util.js): `lib/util.js`

### Message drafting

- [Message drafting](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/llm.js): `lib/llm.js`
- [Lead and message utilities](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/util.js): `lib/util.js`

### WhatsApp outreach

- [WhatsApp connection](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js): `lib/whatsapp.js`
- [WhatsApp session](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js): `lib/whatsapp.js`
- [Send job](https://github.com/oyekamal/maps2whatsapp/blob/master/server.js): `server.js`
- [Sent history](https://github.com/oyekamal/maps2whatsapp/blob/master/lib/whatsapp.js): `lib/whatsapp.js`

### Other components

- **Freelancer**
- **OpenStreetMap Nominatim**
- **Google Maps scraper**
- **Ollama**
- **WhatsApp Web**

## Connections

- Freelancer → Web interface: uses (evidence: `README.md`)
- Web interface → HTTP server: requests actions (evidence: `README.md`)
- HTTP server → Lead search: searches leads (evidence: `server.js`)
- Lead search → Location geocoding: geocodes location (evidence: `lib/scraper.js`)
- Location geocoding → OpenStreetMap Nominatim: queries (evidence: `lib/scraper.js`)
- Lead search → Google Maps scraper: runs query (evidence: `lib/scraper.js`)
- HTTP server → Lead results: stores results (evidence: `server.js`)
- HTTP server → CSV export: exports leads (evidence: `server.js`)
- HTTP server → Message drafting: drafts message (evidence: `server.js`)
- HTTP server → Message drafting: personalizes leads (evidence: `server.js`)
- Message drafting → Ollama: generates text (evidence: `lib/llm.js`)
- Message drafting → Lead and message utilities: renders fallback (evidence: `lib/llm.js`)
- HTTP server → WhatsApp connection: connects account (evidence: `server.js`)
- WhatsApp connection → WhatsApp Web: connects and sends (evidence: `README.md`)
- WhatsApp connection → WhatsApp session: saves session (evidence: `lib/whatsapp.js`)
- HTTP server → Send job: starts send job (evidence: `server.js`)
- Send job → WhatsApp connection: sends messages (evidence: `server.js`)
- Send job → Lead and message utilities: renders template (evidence: `server.js`)
- WhatsApp connection → Sent history: records sends (evidence: `lib/whatsapp.js`)
- HTTP server → Live updates: emits events (evidence: `server.js`)
- Live updates → Web interface: streams status (evidence: `README.md`)
