# sherlock-project/sherlock architecture

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

- Interactive diagram: https://gitdiagram.com/sherlock-project/sherlock
- Repository: https://github.com/sherlock-project/sherlock

## Overview

Sherlock is a username-discovery CLI that checks usernames across hundreds of social networks. The workflow accepts one or more usernames, loads and filters site definitions, probes eligible sites in parallel, classifies responses, and reports or exports findings. The graph also includes the documented selection, proxy, browsing, and output options. Source excerpts show the CLI/search and site-loading responsibilities; some export and option details are documented in the README rather than fully excerpted.

Main entry points: [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.py) (Search coordinator), [`sherlock_project/sites.py`](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sites.py) (Site definitions), [`sherlock_project/notify.py`](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/notify.py) (Live notifications), [`sherlock_project/__main__.py`](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/__main__.py) (Command entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_entry["Command entry<br/>[__main__.py]"]
  node_arguments["Search options<br/>[sherlock.py]"]
end

subgraph group_catalog["Site catalog"]
  node_catalog_loader["Site definitions<br/>[sites.py]"]
  node_site_manifest["Bundled site manifest<br/>[data.json]"]
  node_manifest_service["Remote manifest"]
  node_exclusion_service["Exclusion list"]
end

subgraph group_probe["Account probing"]
  node_engine["Search coordinator<br/>[sherlock.py]"]
end

subgraph group_report["Results and reporting"]
  node_classification["Query classification<br/>[result.py]"]
  node_notifications["Live notifications<br/>[notify.py]"]
  node_exports["Result exports<br/>[sherlock.py]"]
end

node_user(("CLI user"))
node_social_sites["Social networks"]
node_terminal(("Terminal output"))
node_browser["Web browser"]
node_result_files["Output files"]

node_user -->|"starts search"| node_entry
node_entry -->|"dispatches to"| node_arguments
node_arguments -->|"configures"| node_catalog_loader
node_arguments -->|"configures"| node_engine
node_catalog_loader -->|"loads"| node_site_manifest
node_catalog_loader -->|"fetches"| node_manifest_service
node_catalog_loader -->|"fetches exclusions"| node_exclusion_service
node_engine -->|"probes accounts"| node_social_sites
node_engine -->|"creates statuses"| node_classification
node_engine -->|"updates results"| node_notifications
node_notifications -->|"prints findings"| node_terminal
node_notifications -->|"opens matches"| node_browser
node_engine -->|"writes reports"| node_exports
node_exports -->|"saves results"| node_result_files

click node_entry "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/__main__.py"
click node_arguments "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.py"
click node_engine "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.py"
click node_catalog_loader "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sites.py"
click node_site_manifest "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/resources/data.json"
click node_classification "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/result.py"
click node_notifications "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/notify.py"
click node_exports "https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.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_entry,node_arguments,node_user,node_browser toneBlue
class node_catalog_loader,node_site_manifest,node_manifest_service,node_exclusion_service toneAmber
class node_engine toneMint
class node_classification,node_notifications,node_exports toneRose
class node_social_sites,node_terminal,node_result_files toneIndigo
```

## Components

### CLI workflow

- [Command entry](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/__main__.py): `sherlock_project/__main__.py`
- [Search options](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.py): `sherlock_project/sherlock.py`

### Site catalog

- [Site definitions](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sites.py): `sherlock_project/sites.py`
- [Bundled site manifest](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/resources/data.json): `sherlock_project/resources/data.json`
- **Remote manifest**
- **Exclusion list**

### Account probing

- [Search coordinator](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.py): `sherlock_project/sherlock.py`

### Results and reporting

- [Query classification](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/result.py): `sherlock_project/result.py`
- [Live notifications](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/notify.py): `sherlock_project/notify.py`
- [Result exports](https://github.com/sherlock-project/sherlock/blob/master/sherlock_project/sherlock.py): `sherlock_project/sherlock.py`

### Other components

- **CLI user**
- **Social networks**
- **Terminal output**
- **Web browser**
- **Output files**

## Connections

- CLI user → Command entry: starts search
- Command entry → Search options: dispatches to (evidence: `sherlock_project/__main__.py`)
- Search options → Site definitions: configures (evidence: `sherlock_project/sherlock.py`)
- Search options → Search coordinator: configures (evidence: `sherlock_project/sherlock.py`)
- Site definitions → Bundled site manifest: loads (evidence: `sherlock_project/sites.py`)
- Site definitions → Remote manifest: fetches (evidence: `sherlock_project/sites.py`)
- Site definitions → Exclusion list: fetches exclusions (evidence: `sherlock_project/sites.py`)
- Search coordinator → Social networks: probes accounts (evidence: `sherlock_project/sherlock.py`)
- Search coordinator → Query classification: creates statuses (evidence: `sherlock_project/sherlock.py`)
- Search coordinator → Live notifications: updates results (evidence: `sherlock_project/sherlock.py`)
- Live notifications → Terminal output: prints findings (evidence: `sherlock_project/notify.py`)
- Live notifications → Web browser: opens matches (evidence: `sherlock_project/notify.py`)
- Search coordinator → Result exports: writes reports (evidence: `sherlock_project/sherlock.py`)
- Result exports → Output files: saves results
