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

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
• Function signature: validate_zhihu(username: str) -> Result

Political Platforms

• Bitchute: 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 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

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

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	Dynamically loads all validate_<site> functions and coordinates scan execution
user_scanner/core/result.py	Defines the Result dataclass returned by every validator
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, 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.

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