# Where Are the Username Scanning Modules Located in the user-scanner Codebase?

> Find username scanning modules in the user-scanner codebase under user_scanner/user_scan. Explore subdirectories like social, political, and entertainment for platform organization.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: internals
- Published: 2026-09-02

---

**The username scanning modules in user-scanner are located under `user_scanner/user_scan`, with each platform organized by category subdirectories such as `social/`, `political/`, and `entertainment/`.**

The **kaifcodec/user-scanner** repository structures its username-checking logic in a clean, hierarchical package. Understanding this layout is essential for contributing new platforms, debugging existing validators, or importing specific checkers into your own scripts.

## user_scanner/user_scan Directory Structure

All **username scanning modules** reside in the `user_scanner/user_scan` package. The directory is partitioned by **category folders**, with one Python file per supported site.

The canonical path pattern is:

```

user_scanner/user_scan/<category>/<site>.py

```

Each module exposes a function named `validate_<site>` that returns a standardized `Result` object indicating whether a username is available, taken, or resulted in an error.

## Platform Examples by Category

### Social Platforms

- **Zhihu**: [`user_scanner/user_scan/social/zhihu.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/user_scan/social/zhihu.py)
- Function signature: `validate_zhihu(username: str) -> Result`

### Political Platforms

- **Bitchute**: [`user_scanner/user_scan/political/bitchute.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/user_scan/political/bitchute.py)
- Function signature: `validate_bitchute(username: str) -> Result`

Additional categories like `entertainment/` and others follow the same convention—one `.py` file per site with a matching `validate_*` function.

## How the Orchestrator Discovers Modules

The **orchestrator** at [`user_scanner/core/orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/orchestrator.py) automatically discovers and loads all username scanning modules. It traverses the `user_scanner/user_scan` package, imports each `validate_<site>` function dynamically, and executes scans against supplied handles.

This design eliminates manual registration—adding a new platform only requires creating the file in the appropriate category folder.

## Practical Code Examples

### Run Scans Across All Platforms

```python
from user_scanner.core.orchestrator import run_user_scans

# Scan usernames against every supported site

results = run_user_scans(["alice", "bob123"])

for username, site_results in results.items():
    print(f"--- {username} ---")
    for site, result in site_results.items():
        print(f"{site}: {result.status} ({result.extra})")

```

### Import a Single Validator Directly

```python
from user_scanner.user_scan.social.zhihu import validate_zhihu
from user_scanner.core.result import Result

res: Result = validate_zhihu("alice")
print(res.status)   # "available", "taken", or "error"

print(res.extra)    # metadata like profile URL or avatar

```

## Key Supporting Files

| File | Purpose |
|------|---------|
| [`user_scanner/core/orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/orchestrator.py) | Dynamically loads all `validate_<site>` functions and coordinates scan execution |
| [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py) | Defines the `Result` dataclass returned by every validator |
| [`user_scanner/core/engine.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/engine.py) | Provides low-level HTTP utilities (generic requests, impersonation) used by validators |

## Summary

- **Username scanning modules** are stored in `user_scanner/user_scan/<category>/<site>.py`
- Each module implements `validate_<site>(username) -> Result`
- The **orchestrator** auto-discovers modules—no registration boilerplate required
- Categories include `social/`, `political/`, `entertainment/`, and more
- Import individual validators for custom scripts, or use `run_user_scans()` for bulk checks

## Frequently Asked Questions

### How do I add a new username scanning platform to user-scanner?

Create a new Python file in the appropriate category folder under `user_scanner/user_scan/`. Define a function named `validate_<your_site>` that accepts a username string and returns a `Result` object from `user_scanner.core.result`. The orchestrator will automatically detect and include your module in subsequent scans.

### What does the `Result` object contain after a username scan?

According to [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py), the `Result` dataclass includes at minimum a `status` field (typically `"available"`, `"taken"`, or `"error"`) and an `extra` field for additional metadata such as profile URLs, avatar links, or error messages. Specific validators may populate extended fields depending on platform capabilities.

### Can I run username scans for only specific categories or sites?

While `run_user_scans()` executes all discovered validators, you can bypass the orchestrator entirely by importing individual `validate_<site>` functions directly from their module paths, as shown in the single-validator example above. This approach gives you full control over which platforms to query.

### Why are username scanning modules organized by category rather than alphabetically?

The categorical structure in `user_scanner/user_scan/` reflects logical groupings of platforms by domain (social networks, political sites, entertainment services). This organization improves discoverability for contributors and allows the orchestrator to potentially filter or prioritize scans by category in future enhancements.