# katrielmoses/mailaccess architecture

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

- Interactive diagram: https://gitdiagram.com/katrielmoses/mailaccess
- Repository: https://github.com/katrielmoses/mailaccess

## Overview

MailAccess is an email-OSINT product: users investigate an email for linked accounts and identity signals, or harvest public company email addresses from a domain; name-and-domain lookup and hosted Pro enrichment are additional workflows. The map separates the CLI and web entry points, investigation and harvesting stages, enrichment/integrations, and persistence and reporting. README claims preserve major capabilities, but many modules and routes were not sampled, so undocumented internal links are omitted rather than inferred.

Main entry points: [`backend/core/engine.py`](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/engine.py) (Investigation engine), [`backend/core/domain_harvest_orchestrator.py`](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/domain_harvest_orchestrator.py) (Harvest orchestration), [`backend/core/search_provider_router.py`](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/search_provider_router.py) (Search providers), [`cli/main.py`](https://github.com/katrielmoses/mailaccess/blob/main/cli/main.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_web["Web application<br/>[App.tsx]"]
  node_api["API and routes<br/>[main.py]"]
end

subgraph group_investigation["Email investigation"]
  node_engine["Investigation engine<br/>[engine.py]"]
  node_modules["Account checks<br/>[base.py]"]
  node_platforms["Platform sweep"]
  node_signals["Identity and risk<br/>[identity_graph.py]"]
end

subgraph group_harvest["Domain harvesting"]
  node_harvest_cli["Harvest command<br/>[harvest_emails.py]"]
  node_harvest_orchestrator["Harvest orchestration"]
  node_extraction["Email extraction"]
  node_netlas["Netlas sources<br/>[netlas_client.py]"]
end

subgraph group_enrich["Enrichment and integrations"]
  node_pro["Pro enrichment<br/>[enrich.py]"]
  node_search["Search providers"]
  node_http["HTTP transport<br/>[http_client.py]"]
  node_stealth["Stealth transport<br/>[stealth_client.py]"]
end

subgraph group_outputs["Persistence and results"]
  node_database[("Database<br/>[database.py]")]
  node_models["Stored records<br/>[models.py]"]
  node_exports["Report exporters<br/>[base.py]"]
  node_webhooks["Webhook notifications<br/>[webhooks.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"runs commands"| node_cli
node_analyst -->|"uses web app"| node_web
node_web -.->|"calls API"| node_api
node_api -.->|"starts investigations"| node_engine
node_cli -.->|"investigates email"| node_engine
node_engine -->|"runs checks"| node_modules
node_engine -.->|"sweeps platforms"| node_platforms
node_engine -->|"builds identity results"| node_signals
node_analyst -->|"requests domain harvest"| node_harvest_cli
node_harvest_cli -->|"starts harvest"| node_harvest_orchestrator
node_harvest_orchestrator -.->|"extracts addresses"| node_extraction
node_harvest_orchestrator -.->|"queries sources"| node_netlas
node_analyst -->|"requests Pro leads"| node_pro
node_search -->|"uses transport"| node_http
node_search -.->|"uses transport"| node_stealth
node_engine -->|"persists findings"| node_database
node_database -->|"stores records"| node_models
node_analyst -->|"exports reports"| node_exports
node_engine -.->|"notifies results"| node_webhooks

click node_cli "https://github.com/katrielmoses/mailaccess/blob/main/cli/main.py"
click node_web "https://github.com/katrielmoses/mailaccess/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/katrielmoses/mailaccess/blob/main/backend/main.py"
click node_engine "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/engine.py"
click node_modules "https://github.com/katrielmoses/mailaccess/blob/main/backend/modules/base.py"
click node_platforms "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/platform_executor.py"
click node_signals "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/identity_graph.py"
click node_harvest_cli "https://github.com/katrielmoses/mailaccess/blob/main/cli/harvest_emails.py"
click node_harvest_orchestrator "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/domain_harvest_orchestrator.py"
click node_extraction "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/email_extraction.py"
click node_netlas "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/netlas_client.py"
click node_pro "https://github.com/katrielmoses/mailaccess/blob/main/backend/api/routes/enrich.py"
click node_search "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/search_provider_router.py"
click node_http "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/http_client.py"
click node_stealth "https://github.com/katrielmoses/mailaccess/blob/main/backend/core/stealth_client.py"
click node_database "https://github.com/katrielmoses/mailaccess/blob/main/backend/db/database.py"
click node_models "https://github.com/katrielmoses/mailaccess/blob/main/backend/db/models.py"
click node_exports "https://github.com/katrielmoses/mailaccess/blob/main/backend/exporters/base.py"
click node_webhooks "https://github.com/katrielmoses/mailaccess/blob/main/backend/integrations/webhooks.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_web,node_api toneBlue
class node_engine,node_modules,node_platforms,node_signals toneAmber
class node_harvest_cli,node_harvest_orchestrator,node_extraction,node_netlas toneMint
class node_pro,node_search,node_http,node_stealth toneRose
class node_database,node_models,node_exports,node_webhooks,node_analyst toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/katrielmoses/mailaccess/blob/main/cli/main.py): `cli/main.py`
- [Web application](https://github.com/katrielmoses/mailaccess/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API and routes](https://github.com/katrielmoses/mailaccess/blob/main/backend/main.py): `backend/main.py`

### Email investigation

- [Investigation engine](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/engine.py): `backend/core/engine.py`
- [Account checks](https://github.com/katrielmoses/mailaccess/blob/main/backend/modules/base.py): `backend/modules/base.py`
- [Platform sweep](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/platform_executor.py): `backend/core/platform_executor.py`
- [Identity and risk](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/identity_graph.py): `backend/core/identity_graph.py`

### Domain harvesting

- [Harvest command](https://github.com/katrielmoses/mailaccess/blob/main/cli/harvest_emails.py): `cli/harvest_emails.py`
- [Harvest orchestration](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/domain_harvest_orchestrator.py): `backend/core/domain_harvest_orchestrator.py`
- [Email extraction](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/email_extraction.py): `backend/core/email_extraction.py`
- [Netlas sources](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/netlas_client.py): `backend/core/netlas_client.py`

### Enrichment and integrations

- [Pro enrichment](https://github.com/katrielmoses/mailaccess/blob/main/backend/api/routes/enrich.py): `backend/api/routes/enrich.py`
- [Search providers](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/search_provider_router.py): `backend/core/search_provider_router.py`
- [HTTP transport](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/http_client.py): `backend/core/http_client.py`
- [Stealth transport](https://github.com/katrielmoses/mailaccess/blob/main/backend/core/stealth_client.py): `backend/core/stealth_client.py`

### Persistence and results

- [Database](https://github.com/katrielmoses/mailaccess/blob/main/backend/db/database.py): `backend/db/database.py`
- [Stored records](https://github.com/katrielmoses/mailaccess/blob/main/backend/db/models.py): `backend/db/models.py`
- [Report exporters](https://github.com/katrielmoses/mailaccess/blob/main/backend/exporters/base.py): `backend/exporters/base.py`
- [Webhook notifications](https://github.com/katrielmoses/mailaccess/blob/main/backend/integrations/webhooks.py): `backend/integrations/webhooks.py`

### Other components

- **Analyst**

## Connections

- Analyst → CLI: runs commands (evidence: `README.md`)
- Analyst → Web application: uses web app (evidence: `README.md`)
- Web application → API and routes: calls API
- API and routes → Investigation engine: starts investigations
- CLI → Investigation engine: investigates email
- Investigation engine → Account checks: runs checks (evidence: `backend/core/engine.py`)
- Investigation engine → Platform sweep: sweeps platforms
- Investigation engine → Identity and risk: builds identity results (evidence: `backend/core/engine.py`)
- Analyst → Harvest command: requests domain harvest (evidence: `README.md`)
- Harvest command → Harvest orchestration: starts harvest (evidence: `cli/harvest_emails.py`)
- Harvest orchestration → Email extraction: extracts addresses
- Harvest orchestration → Netlas sources: queries sources
- Analyst → Pro enrichment: requests Pro leads (evidence: `README.md`)
- Search providers → HTTP transport: uses transport (evidence: `backend/core/search_provider_router.py`)
- Search providers → Stealth transport: uses transport
- Investigation engine → Database: persists findings (evidence: `backend/core/engine.py`)
- Database → Stored records: stores records (evidence: `backend/db/database.py`)
- Analyst → Report exporters: exports reports (evidence: `README.md`)
- Investigation engine → Webhook notifications: notifies results (evidence: `backend/core/engine.py`)
