# antoniaci/blackbird architecture

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

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

## Overview

Blackbird is a CLI OSINT tool for finding accounts associated with usernames or email addresses, then reviewing and exporting the results. Its main workflow loads platform definitions, applies filters and site-specific checks, and asynchronously searches platforms; optional AI analysis profiles the names of found sites. The README also documents CSV/PDF exports, JSON output and HTML dumps. The graph reflects the sampled search, HTTP, list and AI code; some export wiring is documented but its callers were not fully sampled.

Main entry points: [`blackbird.py`](https://github.com/antoniaci/blackbird/blob/main/blackbird.py) (CLI orchestrator), [`src/modules/core/username.py`](https://github.com/antoniaci/blackbird/blob/main/src/modules/core/username.py) (Username search), [`src/modules/core/email.py`](https://github.com/antoniaci/blackbird/blob/main/src/modules/core/email.py) (Email search), [`src/modules/utils/http_client.py`](https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/http_client.py) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI orchestration"]
  node_cli["CLI orchestrator<br/>[blackbird.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_search["Account discovery"]
  node_username["Username search<br/>[username.py]"]
  node_email["Email search<br/>[email.py]"]
end

subgraph group_support["Search support"]
  node_lists["Site lists<br/>[list_operations.py]"]
  node_username_data["Username definitions<br/>[wmn-metadata.json]"]
  node_email_data["Email definitions<br/>[email-data.json]"]
  node_filter["Site filters<br/>[filter.py]"]
  node_http["HTTP client<br/>[http_client.py]"]
  node_parse["Metadata parsing<br/>[parse.py]"]
  node_precheck["Email pre-check<br/>[precheck.py]"]
  node_instagram["Instagram enrichment<br/>[instagram.py]"]
end

subgraph group_analysis["AI analysis"]
  node_ai_client["AI client<br/>[client.py]"]
  node_key_manager["API key manager<br/>[key_manager.py]"]
  node_ai_service(("Blackbird AI API"))
  node_key_file["API key file"]
end

subgraph group_output["Reports and output"]
  node_csv["CSV export<br/>[csv.py]"]
  node_json_export["JSON export<br/>[json.py]"]
  node_pdf["PDF export<br/>[pdf.py]"]
  node_dump["HTML dumps<br/>[dump.py]"]
end

node_user(("CLI user"))
node_platforms(("Search platforms"))
node_files["Saved output files"]

node_user -->|"provides options"| node_cli
node_cli -->|"sets options"| node_config
node_cli -->|"starts search"| node_username
node_cli -->|"starts search"| node_email
node_username -->|"loads definitions"| node_lists
node_email -->|"loads definitions"| node_lists
node_lists -->|"reads metadata"| node_username_data
node_lists -->|"reads definitions"| node_email_data
node_username -->|"filters sites"| node_filter
node_email -->|"filters sites"| node_filter
node_username -->|"checks accounts"| node_http
node_email -->|"checks accounts"| node_http
node_http -->|"sends requests"| node_platforms
node_username -->|"extracts metadata"| node_parse
node_email -->|"extracts metadata"| node_parse
node_email -->|"prepares requests"| node_precheck
node_username -->|"enriches results"| node_instagram
node_instagram -->|"sends requests"| node_http
node_cli -->|"requests analysis"| node_ai_client
node_ai_client -->|"loads key"| node_key_manager
node_key_manager -->|"reads or writes"| node_key_file
node_key_manager -->|"requests key"| node_http
node_ai_client -->|"sends prompt"| node_http
node_http -->|"sends requests"| node_ai_service
node_cli -->|"exports results"| node_csv
node_cli -->|"exports results"| node_json_export
node_cli -->|"exports results"| node_pdf
node_username -->|"saves responses"| node_dump
node_email -->|"saves responses"| node_dump
node_csv -->|"writes report"| node_files
node_json_export -->|"writes report"| node_files
node_pdf -->|"writes report"| node_files
node_dump -->|"writes HTML"| node_files

click node_cli "https://github.com/antoniaci/blackbird/blob/main/blackbird.py"
click node_config "https://github.com/antoniaci/blackbird/blob/main/src/config.py"
click node_username "https://github.com/antoniaci/blackbird/blob/main/src/modules/core/username.py"
click node_email "https://github.com/antoniaci/blackbird/blob/main/src/modules/core/email.py"
click node_lists "https://github.com/antoniaci/blackbird/blob/main/src/modules/whatsmyname/list_operations.py"
click node_username_data "https://github.com/antoniaci/blackbird/blob/main/data/wmn-metadata.json"
click node_email_data "https://github.com/antoniaci/blackbird/blob/main/data/email-data.json"
click node_filter "https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/filter.py"
click node_http "https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/http_client.py"
click node_parse "https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/parse.py"
click node_precheck "https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/precheck.py"
click node_instagram "https://github.com/antoniaci/blackbird/blob/main/src/modules/sites/instagram.py"
click node_ai_client "https://github.com/antoniaci/blackbird/blob/main/src/modules/ai/client.py"
click node_key_manager "https://github.com/antoniaci/blackbird/blob/main/src/modules/ai/key_manager.py"
click node_csv "https://github.com/antoniaci/blackbird/blob/main/src/modules/export/csv.py"
click node_json_export "https://github.com/antoniaci/blackbird/blob/main/src/modules/export/json.py"
click node_pdf "https://github.com/antoniaci/blackbird/blob/main/src/modules/export/pdf.py"
click node_dump "https://github.com/antoniaci/blackbird/blob/main/src/modules/export/dump.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_user toneBlue
class node_username,node_email toneAmber
class node_lists,node_username_data,node_email_data,node_filter,node_http,node_parse,node_precheck,node_instagram toneMint
class node_ai_client,node_key_manager,node_ai_service,node_key_file toneRose
class node_csv,node_json_export,node_pdf,node_dump,node_platforms,node_files toneIndigo
```

## Components

### CLI orchestration

- [CLI orchestrator](https://github.com/antoniaci/blackbird/blob/main/blackbird.py): `blackbird.py`
- [Runtime config](https://github.com/antoniaci/blackbird/blob/main/src/config.py): `src/config.py`

### Account discovery

- [Username search](https://github.com/antoniaci/blackbird/blob/main/src/modules/core/username.py): `src/modules/core/username.py`
- [Email search](https://github.com/antoniaci/blackbird/blob/main/src/modules/core/email.py): `src/modules/core/email.py`

### Search support

- [Site lists](https://github.com/antoniaci/blackbird/blob/main/src/modules/whatsmyname/list_operations.py): `src/modules/whatsmyname/list_operations.py`
- [Username definitions](https://github.com/antoniaci/blackbird/blob/main/data/wmn-metadata.json): `data/wmn-metadata.json`
- [Email definitions](https://github.com/antoniaci/blackbird/blob/main/data/email-data.json): `data/email-data.json`
- [Site filters](https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/filter.py): `src/modules/utils/filter.py`
- [HTTP client](https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/http_client.py): `src/modules/utils/http_client.py`
- [Metadata parsing](https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/parse.py): `src/modules/utils/parse.py`
- [Email pre-check](https://github.com/antoniaci/blackbird/blob/main/src/modules/utils/precheck.py): `src/modules/utils/precheck.py`
- [Instagram enrichment](https://github.com/antoniaci/blackbird/blob/main/src/modules/sites/instagram.py): `src/modules/sites/instagram.py`

### AI analysis

- [AI client](https://github.com/antoniaci/blackbird/blob/main/src/modules/ai/client.py): `src/modules/ai/client.py`
- [API key manager](https://github.com/antoniaci/blackbird/blob/main/src/modules/ai/key_manager.py): `src/modules/ai/key_manager.py`
- **Blackbird AI API**
- **API key file**

### Reports and output

- [CSV export](https://github.com/antoniaci/blackbird/blob/main/src/modules/export/csv.py): `src/modules/export/csv.py`
- [JSON export](https://github.com/antoniaci/blackbird/blob/main/src/modules/export/json.py): `src/modules/export/json.py`
- [PDF export](https://github.com/antoniaci/blackbird/blob/main/src/modules/export/pdf.py): `src/modules/export/pdf.py`
- [HTML dumps](https://github.com/antoniaci/blackbird/blob/main/src/modules/export/dump.py): `src/modules/export/dump.py`

### Other components

- **CLI user**
- **Search platforms**
- **Saved output files**

## Connections

- CLI user → CLI orchestrator: provides options
- CLI orchestrator → Runtime config: sets options
- CLI orchestrator → Username search: starts search
- CLI orchestrator → Email search: starts search
- Username search → Site lists: loads definitions
- Email search → Site lists: loads definitions
- Site lists → Username definitions: reads metadata
- Site lists → Email definitions: reads definitions
- Username search → Site filters: filters sites
- Email search → Site filters: filters sites
- Username search → HTTP client: checks accounts
- Email search → HTTP client: checks accounts
- HTTP client → Search platforms: sends requests
- Username search → Metadata parsing: extracts metadata
- Email search → Metadata parsing: extracts metadata
- Email search → Email pre-check: prepares requests
- Username search → Instagram enrichment: enriches results
- Instagram enrichment → HTTP client: sends requests
- CLI orchestrator → AI client: requests analysis
- AI client → API key manager: loads key
- API key manager → API key file: reads or writes
- API key manager → HTTP client: requests key
- AI client → HTTP client: sends prompt
- HTTP client → Blackbird AI API: sends requests
- CLI orchestrator → CSV export: exports results
- CLI orchestrator → JSON export: exports results
- CLI orchestrator → PDF export: exports results
- Username search → HTML dumps: saves responses
- Email search → HTML dumps: saves responses
- CSV export → Saved output files: writes report
- JSON export → Saved output files: writes report
- PDF export → Saved output files: writes report
- HTML dumps → Saved output files: writes HTML