# sharsil/mailcat architecture

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

- Interactive diagram: https://gitdiagram.com/sharsil/mailcat
- Repository: https://github.com/sharsil/mailcat

## Overview

Mailcat is a command-line OSINT tool that checks whether email addresses associated with supplied nicknames already exist. Its main workflow accepts one or more usernames (optionally from a file), runs provider-specific checks, and reports matches. The implementation is concentrated in one large module; provider methods include registration and recovery endpoints, SMTP, APIs, and browser-driven checks. The README documents Tor and proxy routing. The excerpt does not show the full dispatcher or result-formatting code, so those internal links are limited to documented behavior.

Main entry points: [`src/mailcat/__init__.py`](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py) (Check orchestration), [`src/mailcat/__main__.py`](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__main__.py) (Module entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_module_entry["Module entry<br/>[__main__.py]"]
  node_cli_runtime["CLI runtime<br/>[__init__.py]"]
  node_username_inputs["Username inputs<br/>[__init__.py]"]
end

subgraph group_checks["Provider checks"]
  node_provider_dispatch["Check orchestration<br/>[__init__.py]"]
  node_registration_checks["Registration checks<br/>[__init__.py]"]
  node_smtp_checks["SMTP checks<br/>[__init__.py]"]
  node_api_checks["API checks<br/>[__init__.py]"]
  node_browser_checks["Browser checks<br/>[__init__.py]"]
end

subgraph group_network["Network routing"]
  node_tor_proxy["Tor / proxy"]
end

subgraph group_results["Results"]
  node_result_output["Match output<br/>[__init__.py]"]
end

node_user(("User"))
node_provider_services{{"Email providers"}}

node_user -->|"runs command"| node_module_entry
node_module_entry -->|"calls main"| node_cli_runtime
node_user -->|"provides names"| node_username_inputs
node_username_inputs -.->|"checks names"| node_provider_dispatch
node_cli_runtime -.->|"starts checks"| node_provider_dispatch
node_provider_dispatch -.->|"dispatches checks"| node_registration_checks
node_provider_dispatch -.->|"dispatches checks"| node_smtp_checks
node_provider_dispatch -.->|"dispatches checks"| node_api_checks
node_provider_dispatch -.->|"dispatches checks"| node_browser_checks
node_registration_checks -->|"queries availability"| node_provider_services
node_smtp_checks -->|"checks addresses"| node_provider_services
node_api_checks -->|"queries availability"| node_provider_services
node_browser_checks -->|"checks availability"| node_provider_services
node_tor_proxy -.->|"routes traffic"| node_smtp_checks
node_tor_proxy -.->|"routes requests"| node_provider_dispatch
node_provider_dispatch -.->|"reports matches"| node_result_output

click node_module_entry "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__main__.py"
click node_cli_runtime "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_username_inputs "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_provider_dispatch "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_registration_checks "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_smtp_checks "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_api_checks "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_browser_checks "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py"
click node_result_output "https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.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_module_entry,node_cli_runtime,node_username_inputs,node_user toneBlue
class node_provider_dispatch,node_registration_checks,node_smtp_checks,node_api_checks,node_browser_checks toneAmber
class node_tor_proxy toneMint
class node_result_output toneRose
class node_provider_services toneIndigo
```

## Components

### Command entry

- [Module entry](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__main__.py): `src/mailcat/__main__.py`
- [CLI runtime](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`
- [Username inputs](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`

### Provider checks

- [Check orchestration](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`
- [Registration checks](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`
- [SMTP checks](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`
- [API checks](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`
- [Browser checks](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`

### Network routing

- **Tor / proxy**

### Results

- [Match output](https://github.com/sharsil/mailcat/blob/main/src/mailcat/__init__.py): `src/mailcat/__init__.py`

### Other components

- **User**
- **Email providers**

## Connections

- User → Module entry: runs command (evidence: `README.md`)
- Module entry → CLI runtime: calls main (evidence: `src/mailcat/__main__.py`)
- User → Username inputs: provides names (evidence: `README.md`)
- Username inputs → Check orchestration: checks names (evidence: `README.md`)
- CLI runtime → Check orchestration: starts checks (evidence: `src/mailcat/__init__.py`)
- Check orchestration → Registration checks: dispatches checks (evidence: `src/mailcat/__init__.py`)
- Check orchestration → SMTP checks: dispatches checks (evidence: `src/mailcat/__init__.py`)
- Check orchestration → API checks: dispatches checks (evidence: `src/mailcat/__init__.py`)
- Check orchestration → Browser checks: dispatches checks (evidence: `src/mailcat/__init__.py`)
- Registration checks → Email providers: queries availability (evidence: `README.md`)
- SMTP checks → Email providers: checks addresses (evidence: `README.md`)
- API checks → Email providers: queries availability (evidence: `README.md`)
- Browser checks → Email providers: checks availability (evidence: `README.md`)
- Tor / proxy → SMTP checks: routes traffic (evidence: `README.md`)
- Tor / proxy → Check orchestration: routes requests (evidence: `README.md`)
- Check orchestration → Match output: reports matches (evidence: `README.md`)