# p1ngul1n0/blackbird architecture

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

- Interactive diagram: https://gitdiagram.com/p1ngul1n0/blackbird
- Repository: https://github.com/p1ngul1n0/blackbird

## Overview

##### Project type and purpose
- Blackbird is an open-source, Python-based CLI OSINT tool that performs fast username/email lookups across 600+ platforms (via WhatsMyName integration) and enriches results with AI-powered profiling.
- It has no persistent database; results are exported to disk (JSON, CSV, PDF). AI integration calls an external model.

##### File structure
- Top-level
- blackbird.py         ← CLI entrypoint
- src/config.py       ← configuration & API key management
- src/modules/        ← core logical layers
- Dockerfile, requirements.txt, tests/, docs/, .github/
- src/modules breakdown
- ai/                 ← AI client & key manager
- core/               ← orchestrator for email/username workflows
- sites/              ← per-site lookup adapters (e.g. instagram.py)
- whatsmyname/        ← integration with community-driven site list
- export/             ← JSON/CSV/PDF/file utilities
- utils/              ← HTTP client, parsing, filtering, logging, input handling
- Tests mirror core and export functionality.

##### README for additional insights
- Describes CLI flags (`--username`, `--email`, `--ai`, `--pdf`)
- AI engine is free, only sends site names
- Integrates with external WhatsMyName project for 600+ sites

##### Main components
A. User & CLI Layer
- User invokes `python blackbird.py` with flags
- CLI Parser & Argument Handler
B. Orchestrator (core modules)
- UsernameSearch / EmailSearch controllers
- Pre-check & filter pipeline
C. Site Lookup Adapters
- modules/sites/*.py
- modules/whatsmyname for dynamic site list
D. AI Profiling
- modules/ai/client.py ← calls external AI service
- modules/ai/key_manager.py
E. Export Layer
- JSON, CSV, PDF generators (modules/export/*.py)
- file_operations for write/read
F. Utilities
- HTTP client, parsing, logging, hashing, user-agent rotation
G. External Services
- 600+ target websites
- AI engine (e.g., OpenAI or custom)
H. File System
- config file (`~/.blackbird/config` or env)
- output directory for exports
I. CI/CD & Documentation (side view)
- GitHub Actions (python-test, auto-close issues)
- Dockerfile for containerization
- GitBook docs

##### Relationships & data flows
1. CLI → Orchestrator
2. Orchestrator → Pre-check util → chooses EmailSearch or UsernameSearch
3. Search workflows → for each site adapter:
a. utils/http_client → send request → utils/parse → filter → result
4. (Optional) Orchestrator → AI client → external AI service → AI profile
5. Results + AI profile → Export layer → write JSON/CSV/PDF → File System
6. User retrieves files

##### Architectural patterns & design principles
- Layered architecture: CLI → service layer (core) → adapter layer (sites, AI) → I/O layer (export, fs)
- Plugin/adapter pattern for adding new site modules
- Utility modules for cross-cutting concerns (HTTP, logging, parsing)
- Separation of concerns: core logic vs. I/O vs. external integrations

##### Technologies & frameworks
- Python 3.x
- pip & requirements.txt
- Docker for containerization
- GitHub Actions for testing & workflows
- PDF generation library (e.g., ReportLab) in modules/export/pdf.py
- External AI API (e.g., OpenAI)
- WhatsMyName community library integration

##### Detail
- Config & key management as a separate component

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and CLI Layer
    User["User"]:::external
    CLI["CLI Parser & Argument Handler"]:::internal
    click CLI "https://github.com/p1ngul1n0/blackbird/blob/main/blackbird.py"
    User -->|invokes| CLI

    %% Configuration
    subgraph "Configuration"
        Config["Configuration & API Key Management"]:::internal
        click Config "https://github.com/p1ngul1n0/blackbird/blob/main/src/config.py"
        Config -->|loads| ConfigFile
    end
    ConfigFile["CLI Environment & .env Support"]:::fs
    click ConfigFile "https://github.com/p1ngul1n0/blackbird/blob/main/.env"
    CLI -->|reads config| Config

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        US["UsernameSearch Controller"]:::internal
        click US "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/core/username.py"
        ES["EmailSearch Controller"]:::internal
        click ES "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/core/email.py"
        PreCheck["Pre-check & Filter Pipeline"]:::internal
        click PreCheck "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/precheck.py"
        Filter["Filtering"]:::internal
        click Filter "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/filter.py"
    end
    CLI -->|flags| US
    CLI -->|flags| ES
    US --> PreCheck
    ES --> PreCheck
    PreCheck --> Filter

    %% Site Lookup Adapters
    subgraph "Site Lookup Adapters"
        Insta["Site Adapter: instagram.py"]:::internal
        click Insta "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/sites/instagram.py"
        WMN["WhatsMyName Integration"]:::internal
        click WMN "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/whatsmyname/list_operations.py"
    end
    Filter -->|username/email| Insta
    Filter -->|username/email| WMN

    %% Utilities
    subgraph "Utilities"
        Http["HTTP Client"]:::internal
        click Http "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/http_client.py"
        Parse["Parsing"]:::internal
        click Parse "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/parse.py"
        Log["Logging"]:::internal
        click Log "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/log.py"
        UA["User-Agent Rotation"]:::internal
        click UA "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/userAgent.py"
        Hash["Hashing"]:::internal
        click Hash "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/hash.py"
        Input["Input Handling"]:::internal
        click Input "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/input.py"
        Permute["Permutation Utilities"]:::internal
        click Permute "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/permute.py"
        FileUtils["Generic File Operations"]:::internal
        click FileUtils "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/utils/file_operations.py"
    end
    Insta --> Http
    WMN --> Http
    Http --> Parse --> Filter
    Http --> Log
    Http --> UA
    Parse --> Filter
    Log --> FileUtils

    %% AI Profiling
    subgraph "AI Profiling"
        AIClient["AI Client"]:::internal
        click AIClient "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/ai/client.py"
        AIKey["AI Key Manager"]:::internal
        click AIKey "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/ai/key_manager.py"
    end
    AIKey -->|reads keys| ConfigFile
    US -->|optional AI request| AIClient
    ES -->|optional AI request| AIClient
    AIClient -->|sends site list| AIService
    AIService["External AI Service"]:::external
    AIService -->|AI response| AIClient

    %% Export Layer
    subgraph "Export Layer"
        JSON["JSON Generator"]:::internal
        click JSON "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/export/json.py"
        CSV["CSV Generator"]:::internal
        click CSV "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/export/csv.py"
        PDF["PDF Generator"]:::internal
        click PDF "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/export/pdf.py"
        Dump["Dump Utilities"]:::internal
        click Dump "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/export/dump.py"
        FileOp["Export File Operations"]:::internal
        click FileOp "https://github.com/p1ngul1n0/blackbird/blob/main/src/modules/export/file_operations.py"
    end
    US -->|results| JSON
    ES -->|results| JSON
    AIClient -->|AI profile| JSON
    JSON --> Dump --> FileOp --> OutputDir
    CSV --> Dump --> FileOp --> OutputDir
    PDF --> Dump --> FileOp --> OutputDir

    OutputDir["Output Directory"]:::fs

    %% CI/CD & Operations
    subgraph "CI/CD & Documentation"
        Docker["Docker Containerization"]:::ops
        click Docker "https://github.com/p1ngul1n0/blackbird/tree/main/Dockerfile"
        TestWF["Python Tests Workflow"]:::ops
        click TestWF "https://github.com/p1ngul1n0/blackbird/blob/main/.github/workflows/python-test.yaml"
        AutoClose["Auto-close Issues Workflow"]:::ops
        click AutoClose "https://github.com/p1ngul1n0/blackbird/blob/main/.github/workflows/auto-close-issues.yaml"
        TestCore["Core & Export Unit Tests"]:::ops
        click TestCore "https://github.com/p1ngul1n0/blackbird/blob/main/tests/test_core.py"
        TestExport["Core & Export Unit Tests"]:::ops
        click TestExport "https://github.com/p1ngul1n0/blackbird/blob/main/tests/test_export.py"
    end

    %% Class Definitions
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef fs fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef ops fill:#fff3cd,stroke:#856404,color:#856404
```
