GhostTrack Project Structure: Complete Guide to the OSINT Utility Files and Organization

GhostTrack organizes its OSINT functionality into four core components: a single Python script (GhostTR.py) containing all tracking logic, a dependency manifest (requirements.txt), project documentation (README.md), and an asset/ directory housing visual resources.

GhostTrack is a lightweight Python-based OSINT (Open Source Intelligence) utility designed for rapid lookups of IP addresses, phone numbers, and usernames. The repository follows a deliberately flat architecture typical of single-purpose security tools, concentrating all operational code in one executable script while externalizing dependencies and documentation. This minimal project structure of GhostTrack eliminates unnecessary abstraction layers, making the tool immediately auditable and modifiable without navigating complex module hierarchies.

Top-Level Repository Layout

The repository root contains exactly four functional elements that comprise the entire application surface:

• GhostTR.py: The main executable implementing the interactive menu and tracker functions
• requirements.txt: Python package dependencies (requests, phonenumbers)
• README.md: Installation instructions, usage examples, and feature screenshots
• asset/: Directory containing banner images and UI screenshots

This flat layout ensures that users can locate critical logic without navigating nested package directories.

Core Files and Their Functions

GhostTR.py – Main Program Logic

Located at the repository root, GhostTR.py serves as the sole entry point for the application. According to the HunxByts/GhostTrack source code, the script implements a text-based menu system that maps user input to four specialized tracker functions through an internal options list.

The file contains the following primary functions:

• IP_Track: Performs geolocation lookups via HTTP requests to IP intelligence APIs, parsing JSON responses and printing formatted output with colored terminal escape codes
• phoneGW: Validates and analyzes phone numbers using the phonenumbers library
• TrackLu: Queries username availability across social media platforms using hard-coded URL templates
• showIP: Retrieves the user's public IP address from https://api.ipify.org/

Each function executes synchronous HTTP requests, parses the JSON responses, and formats results for terminal display.

requirements.txt – Dependency Management

This file lists the minimal external dependencies required to execute the tracker:

• requests – For HTTP API calls within the tracking functions
• phonenumbers – For parsing and validating international phone number formats in phoneGW

Users install these dependencies via pip install -r requirements.txt before executing the main script.

README.md – Documentation Gateway

The README provides setup instructions, feature descriptions, and visual demonstrations. It embeds images from the asset/ directory to illustrate each tracker interface, guiding new users through the clone-install-launch workflow.

The Asset Directory

The asset/ folder contains visual resources referenced by the documentation:

• bn.png: Header banner displayed at the top of the README
• ip.png: Screenshot demonstrating the IP Tracker user interface
• phone.png: Screenshot of the Phone Number Tracker output
• User.png: Screenshot showing the Username Tracker results
• text: Placeholder file (currently contains "Image..")

These assets provide visual context for the tool's terminal-based interfaces without affecting runtime functionality.

How the Components Interact

The execution flow follows a simple linear pattern:

1. The user launches python3 GhostTR.py, which displays the interactive menu and ASCII art banner
2. Menu selections trigger the corresponding tracker function—IP_Track (option 1), showIP (option 2), phoneGW (option 3), or TrackLu (option 4)
3. Each function executes HTTP requests to external APIs, parses the JSON responses, and prints formatted results to stdout
4. The phonenumbers library (installed via requirements.txt) validates phone inputs before processing in phoneGW
5. Hard-coded URL templates in TrackLu check username availability across platforms, displaying URLs only for endpoints returning HTTP 200 responses

No configuration files or environment variables are required; the script operates using hard-coded endpoints and immediate user input.

Running GhostTrack

To deploy the tool from source, execute the following sequence:

git clone https://github.com/HunxByts/GhostTrack.git
cd GhostTrack
pip3 install -r requirements.txt
python3 GhostTR.py

Once launched, the script presents a numbered menu. Selecting option 1 initiates IP_Track, option 2 executes showIP, option 3 runs phoneGW, and option 4 launches TrackLu.

Summary

• GhostTrack uses a flat repository structure with all Python logic concentrated in GhostTR.py
• The requirements.txt file manages the two external dependencies (requests and phonenumbers)
• Four core functions (IP_Track, phoneGW, TrackLu, showIP) handle all OSINT operations within a single script
• The asset/ directory contains documentation images and screenshots, not runtime dependencies
• The tool requires no configuration files, operating entirely through hard-coded API endpoints and interactive prompts

Frequently Asked Questions

What is the main entry point in the GhostTrack project structure?

The main entry point is GhostTR.py located in the repository root. This script contains the menu system and all tracking logic, making it the only file required to run the application after dependencies are installed.

What Python dependencies does GhostTrack require?

According to the requirements.txt file, GhostTrack requires two external packages: requests for HTTP API calls and phonenumbers for phone number validation and formatting. These are the only third-party libraries needed to execute the tracker functions.

How does GhostTrack organize its visual assets?

Visual resources are stored in the asset/ directory, which contains PNG screenshots (ip.png, phone.png, User.png) and a banner image (bn.png) referenced by the README. These files illustrate the terminal interfaces but are not loaded during script execution.

Can GhostTrack be extended with additional tracking modules?

Yes. Since all logic resides in GhostTR.py, developers can add new tracker functions following the pattern of existing implementations like IP_Track or phoneGW, then append them to the options list to integrate new menu items and expand the tool's OSINT capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}