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

> Understand the GhostTrack project structure. Explore the OSINT utility's Python script, requirements, documentation, and asset files for efficient organization and use.

- Repository: [K1LLU/GhostTrack](https://github.com/HunxByts/GhostTrack)
- Tags: architecture
- Published: 2026-04-29

---

**GhostTrack organizes its OSINT functionality into four core components: a single Python script ([`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py)) containing all tracking logic, a dependency manifest ([`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt)), project documentation ([`README.md`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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:

```bash
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`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py)
- The **[`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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`](https://github.com/HunxByts/GhostTrack/blob/main/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.