# koff75/wifi-position-tracker architecture

> Architecture diagram of the GitHub repository koff75/wifi-position-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koff75/wifi-position-tracker
- Repository: https://github.com/koff75/wifi-position-tracker

## Overview

##### Project Type and Purpose
- This is a Node.js–based command-line toolkit (CLI) for geolocating WiFi BSSIDs via Apple’s undocumented location API.
- It provides two entry points:
- bssid-geolocator.js – core geolocation and comparison tool
- scan_and_map.js – Windows-only WiFi scanner + mapper

##### File Structure
- Top‐level files only (no nested directories):
- bssid-geolocator.js – main CLI for geolocating and comparing BSSIDs
- scan_and_map.js – wraps Windows `netsh` scan, invokes bssid-geolocator logic, and outputs KML
- bssid.proto – Protocol Buffer schema for Apple’s API
- README.md, LICENSE, .gitignore

- Patterns and architecture hints:
- CLI argument parsing & interactive UI (yargs, inquirer)
- Protocol-buffer encoding/decoding (protobufjs)
- HTTP transport (axios) to external Apple service
- Concurrency control (p-limit), retry/backoff, error handling
- Output modules: console, TSV, JSON, KML (xmlbuilder2)

##### Extract Architectural Insights from README
- Core workflow:
User input → CLI parser → Request builder → Apple API → Response processor → Output generator
- scan_and_map.js augments this by first retrieving SSIDs/BSSIDs via `netsh` (Windows), then pipelines them through the same core.
- Movement comparison: accepts a previous JSON, computes distances, filters, then includes movement metadata in JSON/KML.

a. Main Components
- CLI Frontend
– bssid-geolocator.js (flags, interactive mode)
– scan_and_map.js (Windows netsh wrapper)
- Input Sources
– User (stdin prompts via inquirer)
– BSSID list file (fs.readFile)
– Windows `netsh` scan output
– Previous JSON (for movement compare)
- Core Processing
– Argument Parser (yargs)
– Interactive UI (inquirer)
– BSSID Normalizer
– Protobuf Encoder/Decoder (protobufjs with bssid.proto)
– HTTP Client (axios) + concurrency manager (p-limit) + retry/backoff
– Response Sanitizer & Error Handler
– Movement Detection Engine (optional compare module)
- Output Generators
– Console Formatter (TSV table)
– JSON Writer
– KML Builder (xmlbuilder2)
- External Services
– Apple Location Services API
– Windows `netsh` command

b. Relationships & Data Flow
1. User or script invokes bssid-geolocator.js / scan_and_map.js
2. CLI Parser reads flags or launches interactive prompts
3. Input module loads BSSIDs (stdin, file, or netsh scan)
4. Core Processing loops over BSSIDs:
– Normalize MAC
– Encode request (protobuf)
– Send HTTP POST to Apple service (axios) under concurrency limits
– Handle errors and retries
– Decode response, extract lat/lon, hacc, timestamp, channel
5. Optional: If --compare is set, load previous JSON → Movement Detection → annotate moved BSSIDs
6. Output module formats and writes results → console, JSON, TSV, KML
7. scan_and_map.js: embeds step 3 by invoking `netsh`, parses results, then follows the same pipeline

c. Architectural Patterns & Principles
- Modular separation of concerns: parsing, processing, output
- Pipeline pattern for streaming BSSID data
- Concurrency control with p-limit to avoid rate-limit errors
- Retry with exponential backoff for resilience
- Stateless core processing functions for testability

d. Key Technologies & Libraries
- Node.js & npm (runtime)
- yargs (CLI arguments)
- inquirer (interactive)
- protobufjs + bssid.proto (message encoding)
- axios (HTTP)
- p-limit (concurrency)
- xmlbuilder2 (KML)
- iconv-lite (Windows charset conversion in scan script)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Frontend"
        A["bssid-geolocator.js"]:::entry
        B["scan_and_map.js"]:::entry
    end

    subgraph "Inputs"
        U["User (stdin prompts)"]:::input
        FFILE["BSSID list file"]:::input
        NSCAN["Windows netsh output"]:::input
    end

    subgraph "Core Processing"
        C["Argument Parser (yargs)"]:::core
        D["Interactive UI (inquirer)"]:::core
        E["BSSID Normalizer"]:::core
        P["Protobuf Encoder/Decoder"]:::core
        HTP["HTTP Client + p-limit + retry"]:::core
        RESP["Response Sanitizer & Error Handler"]:::core
        MOVE["Movement Detection Engine"]:::core
    end

    subgraph "Outputs"
        O1["Console Formatter (TSV)"]:::output
        O2["JSON Writer"]:::output
        O3["KML Builder (xmlbuilder2)"]:::output
    end

    subgraph "External Services"
        APPI["Apple Location API"]:::external
        NETSH["Windows netsh command"]:::external
    end

    A --> C
    B --> NSCAN
    U --> C
    FFILE --> C
    NSCAN --> C

    C --> D
    D --> E
    C --> E

    E --> P
    P --> HTP
    HTP --> APPI
    APPI --> RESP
    RESP --> MOVE
    RESP -.-> O1
    RESP -.-> O2
    RESP -.-> O3
    MOVE --> O1
    MOVE --> O2
    MOVE --> O3

    click A "https://github.com/koff75/wifi-position-tracker/blob/main/bssid-geolocator.js"
    click B "https://github.com/koff75/wifi-position-tracker/blob/main/scan_and_map.js"
    click P "https://github.com/koff75/wifi-position-tracker/blob/main/bssid.proto"
    click README["README.md"] "README.md"
    click LICENSE["LICENSE"] "LICENSE"
    click GIT[".gitignore"] ".gitignore"

    style README fill:#FFFFFF,stroke:#000000
    style LICENSE fill:#FFFFFF,stroke:#000000
    style GIT fill:#FFFFFF,stroke:#000000

    classDef input fill:#ADD8E6,stroke:#000000;
    classDef core fill:#90EE90,stroke:#000000;
    classDef external fill:#D3D3D3,stroke:#000000;
    classDef output fill:#FFFF99,stroke:#000000;
    classDef entry fill:#ADD8E6,stroke:#000000;
```
