# domenicoverde/vowifi-map architecture

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

- Interactive diagram: https://gitdiagram.com/domenicoverde/vowifi-map
- Repository: https://github.com/domenicoverde/vowifi-map

## Overview

vowifi-map scans mobile operators’ public ePDG endpoints and presents the resulting availability and locations on an interactive map. The backend loads operator data, performs DNS/IP-location/IKE checks, and writes a JSON report; the frontend loads that report and renders map markers, details, statistics, and theme controls. Backend stage ordering is documented in the README, but the sampled excerpts do not show the scanner’s internal calls, so those links cite the README. Protocol modules are included, though their internal relationships are not established by the excerpts.

Main entry points: [`frontend/src/App.tsx`](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/App.tsx) (Frontend app), [`backend/src/cmd/main.go`](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/cmd/main.go) (Scanner CLI), [`backend/src/internal/scan/scan.go`](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/scan.go) (Scan coordinator), [`frontend/src/components/MapView.tsx`](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/MapView.tsx) (Interactive map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend scanning"]
  node_operator[("Operator catalog<br/>[csv.go]")]
  node_geoip["GeoIP lookup<br/>[geoip.go]"]
  node_scanner["Scan coordinator<br/>[scan.go]"]
  node_dns["DNS resolution<br/>[dns.go]"]
  node_probe["IKE probe<br/>[ike.go]"]
  node_scan_types["Scan data types<br/>[types.go]"]
  node_cli["Scanner CLI<br/>[main.go]"]
end

subgraph group_ike["IKEv2 protocol"]
  node_ike_build["IKE message build<br/>[build.go]"]
  node_ike_message["IKE message codec<br/>[message.go]"]
  node_ike_request["IKE request<br/>[request.go]"]
  node_ike_security["IKE security<br/>[security.go]"]
  node_ike_types["IKE types<br/>[types.go]"]
end

subgraph group_frontend["Interactive map"]
  node_app["Frontend app<br/>[App.tsx]"]
  node_header["Map summary<br/>[Header.tsx]"]
  node_map["Interactive map<br/>[MapView.tsx]"]
  node_popup["ePDG details<br/>[EpdgPopup.tsx]"]
  node_marker_icon["Status markers<br/>[markerIcon.ts]"]
  node_flags["Country flags<br/>[flagEmoji.ts]"]
  node_theme_toggle["Theme control<br/>[ThemeToggle.tsx]"]
  node_theme_state["Theme state<br/>[useTheme.ts]"]
  node_entry["Browser entry<br/>[main.tsx]"]
end

node_report["JSON report"]
node_browser(("Map visitor"))

node_cli -->|"loads operators"| node_operator
node_cli -->|"opens database"| node_geoip
node_cli -->|"scans operators"| node_scanner
node_scanner -->|"resolves hostnames"| node_dns
node_scanner -->|"geolocates IPs"| node_geoip
node_scanner -->|"probes endpoints"| node_probe
node_cli -->|"writes JSON"| node_report
node_browser -.->|"opens app"| node_entry
node_entry -->|"renders"| node_app
node_app -->|"fetches markers"| node_report
node_app -->|"renders summary"| node_header
node_app -->|"renders markers"| node_map
node_app -->|"renders control"| node_theme_toggle
node_app -->|"uses theme"| node_theme_state
node_map -->|"renders details"| node_popup
node_map -->|"selects icons"| node_marker_icon
node_popup -->|"formats flag"| node_flags

click node_operator "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/persistence/csv.go"
click node_geoip "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/persistence/geoip.go"
click node_scanner "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/scan.go"
click node_dns "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/dns.go"
click node_probe "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/ike.go"
click node_scan_types "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/types.go"
click node_cli "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/cmd/main.go"
click node_ike_build "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/build.go"
click node_ike_message "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/message.go"
click node_ike_request "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/request.go"
click node_ike_security "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/security.go"
click node_ike_types "https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/types.go"
click node_app "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/App.tsx"
click node_header "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/Header.tsx"
click node_map "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/MapView.tsx"
click node_popup "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/EpdgPopup.tsx"
click node_marker_icon "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/markerIcon.ts"
click node_flags "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/flagEmoji.ts"
click node_theme_toggle "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/ThemeToggle.tsx"
click node_theme_state "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/useTheme.ts"
click node_entry "https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/main.tsx"

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_operator,node_geoip,node_scanner,node_dns,node_probe,node_scan_types,node_cli toneBlue
class node_ike_build,node_ike_message,node_ike_request,node_ike_security,node_ike_types toneAmber
class node_app,node_header,node_map,node_popup,node_marker_icon,node_flags,node_theme_toggle,node_theme_state,node_entry toneMint
class node_report,node_browser toneIndigo
```

## Components

### Backend scanning

- [Operator catalog](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/persistence/csv.go): `backend/src/internal/persistence/csv.go`
- [GeoIP lookup](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/persistence/geoip.go): `backend/src/internal/persistence/geoip.go`
- [Scan coordinator](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/scan.go): `backend/src/internal/scan/scan.go`
- [DNS resolution](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/dns.go): `backend/src/internal/scan/dns.go`
- [IKE probe](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/ike.go): `backend/src/internal/scan/ike.go`
- [Scan data types](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/scan/types.go): `backend/src/internal/scan/types.go`
- [Scanner CLI](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/cmd/main.go): `backend/src/cmd/main.go`

### IKEv2 protocol

- [IKE message build](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/build.go): `backend/src/internal/ike/build.go`
- [IKE message codec](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/message.go): `backend/src/internal/ike/message.go`
- [IKE request](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/request.go): `backend/src/internal/ike/request.go`
- [IKE security](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/security.go): `backend/src/internal/ike/security.go`
- [IKE types](https://github.com/domenicoverde/vowifi-map/blob/main/backend/src/internal/ike/types.go): `backend/src/internal/ike/types.go`

### Interactive map

- [Frontend app](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Map summary](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/Header.tsx): `frontend/src/components/Header.tsx`
- [Interactive map](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/MapView.tsx): `frontend/src/components/MapView.tsx`
- [ePDG details](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/EpdgPopup.tsx): `frontend/src/components/EpdgPopup.tsx`
- [Status markers](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/markerIcon.ts): `frontend/src/markerIcon.ts`
- [Country flags](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/flagEmoji.ts): `frontend/src/flagEmoji.ts`
- [Theme control](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/components/ThemeToggle.tsx): `frontend/src/components/ThemeToggle.tsx`
- [Theme state](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/useTheme.ts): `frontend/src/useTheme.ts`
- [Browser entry](https://github.com/domenicoverde/vowifi-map/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`

### Other components

- **JSON report**
- **Map visitor**

## Connections

- Scanner CLI → Operator catalog: loads operators (evidence: `backend/src/cmd/main.go`)
- Scanner CLI → GeoIP lookup: opens database (evidence: `backend/src/cmd/main.go`)
- Scanner CLI → Scan coordinator: scans operators (evidence: `backend/src/cmd/main.go`)
- Scan coordinator → DNS resolution: resolves hostnames (evidence: `README.md`)
- Scan coordinator → GeoIP lookup: geolocates IPs (evidence: `README.md`)
- Scan coordinator → IKE probe: probes endpoints (evidence: `README.md`)
- Scanner CLI → JSON report: writes JSON (evidence: `backend/src/cmd/main.go`)
- Map visitor → Browser entry: opens app
- Browser entry → Frontend app: renders (evidence: `frontend/src/main.tsx`)
- Frontend app → JSON report: fetches markers (evidence: `frontend/src/App.tsx`)
- Frontend app → Map summary: renders summary (evidence: `frontend/src/App.tsx`)
- Frontend app → Interactive map: renders markers (evidence: `frontend/src/App.tsx`)
- Frontend app → Theme control: renders control (evidence: `frontend/src/App.tsx`)
- Frontend app → Theme state: uses theme (evidence: `frontend/src/App.tsx`)
- Interactive map → ePDG details: renders details (evidence: `frontend/src/components/MapView.tsx`)
- Interactive map → Status markers: selects icons (evidence: `frontend/src/components/MapView.tsx`)
- ePDG details → Country flags: formats flag (evidence: `frontend/src/components/EpdgPopup.tsx`)
