# osint-experts-society/consensus-osint architecture

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

- Interactive diagram: https://gitdiagram.com/osint-experts-society/consensus-osint
- Repository: https://github.com/osint-experts-society/consensus-osint

## Overview

Consensus is a command-line OSINT lookup application for usernames, email addresses, and phone numbers. A user starts a scan through the CLI or interactive terminal; the CLI selects checks, runs data-driven site rules and adapted code modules, then presents unified findings and can export reports. Phone lookup additionally provides offline number analysis and search-dork suggestions. The README also describes broad merged coverage and deduplicated default searches. Relationships below are limited to excerpted source references and README statements; several domain subsystems are present in the tree but their wiring was not sampled.

Main entry points: [`consensus_osint/cli.py`](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/cli.py) (Command-line Scanner), [`consensus_osint/core/models.py`](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/models.py) (Unified Findings), [`consensus_osint/core/modules.py`](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/modules.py) (Module Registry), [`consensus_osint/core/reports.py`](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/reports.py) (Report Export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interface"]
  node_cli["Command-line Scanner<br/>[cli.py]"]
  node_terminal["Interactive Terminal<br/>[interactive.py]"]
  node_terminal_ui["Terminal UI<br/>[terminal_ui.py]"]
  node_console["Console Output<br/>[console.py]"]
  node_mcp["MCP Interface<br/>[mcp_server.py]"]
end

subgraph group_scan["Lookup Workflow"]
  node_scan_control["Scan Controls<br/>[scan_control.py]"]
  node_scan_budget["Scan Budget<br/>[scan_budget.py]"]
  node_phone["Phone Analysis<br/>[phone.py]"]
end

subgraph group_catalog["Check Catalog"]
  node_sitesdb["Site Rules<br/>[sitesdb.py]"]
  node_modules["Module Registry<br/>[modules.py]"]
  node_adapters["Project Adapters"]
  node_profile_contracts["Profile Contracts"]
  node_mailbox_contracts["Mailbox Contracts"]
end

subgraph group_results["Results and Reports"]
  node_models["Unified Findings<br/>[models.py]"]
  node_presentation["Result Interpretation<br/>[presentation.py]"]
  node_reports["Report Export<br/>[reports.py]"]
end

subgraph group_support["Session Support"]
  node_config["Configuration<br/>[config.py]"]
  node_session_info["Session Details<br/>[session_info.py]"]
  node_install_manager["Managed Installer<br/>[install_manager.py]"]
end

node_user(("User"))
node_external_sites(("Lookup Sites"))
node_local_phone_data[("Phone Metadata")]

node_user -->|"starts lookup"| node_cli
node_user -->|"uses"| node_terminal
node_terminal -->|"dispatches commands"| node_cli
node_cli -->|"loads rules"| node_sitesdb
node_cli -->|"selects checks"| node_modules
node_modules -->|"loads families"| node_adapters
node_modules -->|"uses result types"| node_models
node_adapters -->|"normalizes results"| node_models
node_adapters -->|"implements modules"| node_modules
node_sitesdb -->|"defines checks"| node_external_sites
node_cli -->|"analyzes numbers"| node_phone
node_phone -->|"reads metadata"| node_local_phone_data
node_cli -->|"limits checks"| node_scan_budget
node_cli -->|"controls scans"| node_scan_control
node_cli -->|"collects findings"| node_models
node_cli -->|"prints results"| node_console
node_console -->|"formats findings"| node_presentation
node_console -->|"offers exports"| node_reports
node_reports -->|"reads summaries"| node_models
node_reports -->|"uses interpretation"| node_presentation
node_terminal -->|"uses terminal UI"| node_terminal_ui
node_terminal_ui -->|"dispatches controls"| node_scan_control
node_mcp -->|"invokes scanner"| node_cli
node_mcp -->|"uses result formats"| node_reports
node_config -->|"configures catalog"| node_sitesdb
node_session_info -.->|"identifies session"| node_config
node_install_manager -.->|"retrieves releases"| node_external_sites
node_profile_contracts -->|"uses finding types"| node_models
node_mailbox_contracts -->|"uses finding types"| node_models

click node_cli "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/cli.py"
click node_terminal "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/interactive.py"
click node_terminal_ui "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/terminal_ui.py"
click node_console "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/console.py"
click node_scan_control "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/scan_control.py"
click node_scan_budget "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/scan_budget.py"
click node_phone "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/phone.py"
click node_sitesdb "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/sitesdb.py"
click node_modules "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/modules.py"
click node_adapters "https://github.com/osint-experts-society/consensus-osint/tree/main/consensus_osint/adapters"
click node_profile_contracts "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/profile_api_contracts.py"
click node_mailbox_contracts "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/mailbox_contracts.py"
click node_models "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/models.py"
click node_presentation "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/presentation.py"
click node_reports "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/reports.py"
click node_mcp "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/mcp_server.py"
click node_config "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/config.py"
click node_session_info "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/session_info.py"
click node_install_manager "https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/install_manager.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_terminal,node_terminal_ui,node_console,node_mcp,node_user toneBlue
class node_scan_control,node_scan_budget,node_phone,node_local_phone_data toneAmber
class node_sitesdb,node_modules,node_adapters,node_profile_contracts,node_mailbox_contracts toneMint
class node_models,node_presentation,node_reports toneRose
class node_config,node_session_info,node_install_manager,node_external_sites toneIndigo
```

## Components

### User Interface

- [Command-line Scanner](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/cli.py): `consensus_osint/cli.py`
- [Interactive Terminal](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/interactive.py): `consensus_osint/core/interactive.py`
- [Terminal UI](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/terminal_ui.py): `consensus_osint/core/terminal_ui.py`
- [Console Output](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/console.py): `consensus_osint/core/console.py`
- [MCP Interface](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/mcp_server.py): `consensus_osint/mcp_server.py`

### Lookup Workflow

- [Scan Controls](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/scan_control.py): `consensus_osint/core/scan_control.py`
- [Scan Budget](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/scan_budget.py): `consensus_osint/core/scan_budget.py`
- [Phone Analysis](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/phone.py): `consensus_osint/core/phone.py`

### Check Catalog

- [Site Rules](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/sitesdb.py): `consensus_osint/core/sitesdb.py`
- [Module Registry](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/modules.py): `consensus_osint/core/modules.py`
- [Project Adapters](https://github.com/osint-experts-society/consensus-osint/tree/main/consensus_osint/adapters): `consensus_osint/adapters`
- [Profile Contracts](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/profile_api_contracts.py): `consensus_osint/core/profile_api_contracts.py`
- [Mailbox Contracts](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/mailbox_contracts.py): `consensus_osint/core/mailbox_contracts.py`

### Results and Reports

- [Unified Findings](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/models.py): `consensus_osint/core/models.py`
- [Result Interpretation](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/presentation.py): `consensus_osint/core/presentation.py`
- [Report Export](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/reports.py): `consensus_osint/core/reports.py`

### Session Support

- [Configuration](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/config.py): `consensus_osint/core/config.py`
- [Session Details](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/session_info.py): `consensus_osint/core/session_info.py`
- [Managed Installer](https://github.com/osint-experts-society/consensus-osint/blob/main/consensus_osint/core/install_manager.py): `consensus_osint/core/install_manager.py`

### Other components

- **User**
- **Lookup Sites**
- **Phone Metadata**

## Connections

- User → Command-line Scanner: starts lookup (evidence: `consensus_osint/cli.py`)
- User → Interactive Terminal: uses (evidence: `consensus_osint/core/interactive.py`)
- Interactive Terminal → Command-line Scanner: dispatches commands (evidence: `consensus_osint/core/interactive.py`)
- Command-line Scanner → Site Rules: loads rules (evidence: `consensus_osint/cli.py`)
- Command-line Scanner → Module Registry: selects checks (evidence: `consensus_osint/cli.py`)
- Module Registry → Project Adapters: loads families (evidence: `consensus_osint/core/modules.py`)
- Module Registry → Unified Findings: uses result types (evidence: `consensus_osint/core/modules.py`)
- Project Adapters → Unified Findings: normalizes results (evidence: `consensus_osint/adapters/user_scanner_adapter.py`)
- Project Adapters → Module Registry: implements modules (evidence: `consensus_osint/adapters/user_scanner_adapter.py`)
- Site Rules → Lookup Sites: defines checks (evidence: `consensus_osint/core/sitesdb.py`)
- Command-line Scanner → Phone Analysis: analyzes numbers (evidence: `consensus_osint/cli.py`)
- Phone Analysis → Phone Metadata: reads metadata (evidence: `consensus_osint/core/phone.py`)
- Command-line Scanner → Scan Budget: limits checks (evidence: `consensus_osint/cli.py`)
- Command-line Scanner → Scan Controls: controls scans (evidence: `consensus_osint/cli.py`)
- Command-line Scanner → Unified Findings: collects findings (evidence: `consensus_osint/cli.py`)
- Command-line Scanner → Console Output: prints results (evidence: `consensus_osint/cli.py`)
- Console Output → Result Interpretation: formats findings (evidence: `consensus_osint/core/console.py`)
- Console Output → Report Export: offers exports (evidence: `consensus_osint/core/console.py`)
- Report Export → Unified Findings: reads summaries (evidence: `consensus_osint/core/reports.py`)
- Report Export → Result Interpretation: uses interpretation (evidence: `consensus_osint/core/reports.py`)
- Interactive Terminal → Terminal UI: uses terminal UI (evidence: `consensus_osint/core/interactive.py`)
- Terminal UI → Scan Controls: dispatches controls (evidence: `consensus_osint/core/terminal_ui.py`)
- MCP Interface → Command-line Scanner: invokes scanner (evidence: `consensus_osint/mcp_server.py`)
- MCP Interface → Report Export: uses result formats (evidence: `consensus_osint/mcp_server.py`)
- Configuration → Site Rules: configures catalog (evidence: `consensus_osint/core/config.py`)
- Session Details → Configuration: identifies session
- Managed Installer → Lookup Sites: retrieves releases
- Profile Contracts → Unified Findings: uses finding types (evidence: `consensus_osint/core/profile_api_contracts.py`)
- Mailbox Contracts → Unified Findings: uses finding types (evidence: `consensus_osint/core/mailbox_contracts.py`)