# snifsnsort/mailguard architecture

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

- Interactive diagram: https://gitdiagram.com/snifsnsort/mailguard
- Repository: https://github.com/snifsnsort/mailguard

## Overview

MailGuard audits connected Microsoft 365 and Google Workspace tenants, scores security findings, and reports posture and lookalike-domain risks. The principal workflow is tenant connection, scan initiation, platform-specific checks, persisted scan results, and dashboard/history review. README capabilities are included where source excerpts are limited; dashed edges mark relationships that are documented at the product level or not directly demonstrated by the sampled code.

Main entry points: [`backend/app/services/scan_engine.py`](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/scan_engine.py) (Scan orchestrator), [`frontend/src/App.jsx`](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/App.jsx) (React application), [`backend/app/main.py`](https://github.com/snifsnsort/mailguard/blob/main/backend/app/main.py) (API router), [`backend/app/api/google_auth.py`](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/google_auth.py) (Google OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_app["React application<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_dashboard["Posture dashboard<br/>[Dashboard.jsx]"]
  node_checks["Security checks<br/>[Checks.jsx]"]
  node_history["Scan history<br/>[History.jsx]"]
  node_lookalike_ui["Lookalike review<br/>[LookalikeScan.jsx]"]
end

subgraph group_api["API workflows"]
  node_api_routes["API router<br/>[main.py]"]
  node_tenant_api["Tenant management<br/>[tenants.py]"]
  node_scan_api["Scan operations<br/>[scans.py]"]
  node_report_api["PDF reports<br/>[reports.py]"]
  node_aggressive_api["Lookalike endpoints<br/>[aggressive_scan.py]"]
  node_onboarding_api["Onboarding<br/>[onboarding.py]"]
end

subgraph group_scan["Security analysis"]
  node_engine["Scan orchestrator<br/>[scan_engine.py]"]
  node_m365_checks["M365 checks<br/>[graph_client.py]"]
  node_exchange_checks["Exchange checks"]
  node_mx_analysis["MX analysis<br/>[mx_analyzer.py]"]
  node_gws_checks["Google checks"]
  node_domain_detector["Lookalike detection"]
  node_aggressive_scan["Threat enrichment"]
  node_report_generator["Report generation"]
end

subgraph group_identity["Tenant connections"]
  node_oauth["Google OAuth<br/>[google_auth.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_security["Token encryption<br/>[security.py]"]
end

subgraph group_state["Persistence"]
  node_tenant_store[("Tenant records<br/>[tenant.py]")]
  node_scan_store[("Scan records<br/>[scan.py]")]
  node_aggressive_store[("Threat scan records<br/>[aggressive_scan.py]")]
  node_database[("Database access<br/>[database.py]")]
end

node_admin(("Tenant admin"))
node_microsoft["Microsoft 365"]
node_google["Google Workspace"]
node_dns["Public DNS"]

node_admin -->|"uses"| node_app
node_app -->|"requests data"| node_api_client
node_app -->|"renders"| node_dashboard
node_app -->|"routes to"| node_checks
node_app -->|"routes to"| node_history
node_app -->|"routes to"| node_lookalike_ui
node_api_client -.->|"calls API"| node_api_routes
node_api_routes -->|"registers"| node_tenant_api
node_api_routes -->|"registers"| node_scan_api
node_api_routes -->|"registers"| node_report_api
node_api_routes -->|"registers"| node_aggressive_api
node_api_routes -->|"registers"| node_onboarding_api
node_tenant_api -->|"reads and writes"| node_tenant_store
node_scan_api -->|"starts scan"| node_engine
node_scan_api -->|"reads and writes"| node_scan_store
node_engine -->|"queries"| node_m365_checks
node_engine -->|"queries"| node_exchange_checks
node_engine -->|"uses"| node_mx_analysis
node_engine -->|"queries"| node_gws_checks
node_engine -->|"checks domains"| node_domain_detector
node_engine -.->|"persists results"| node_scan_store
node_m365_checks -->|"queries tenant"| node_microsoft
node_gws_checks -.->|"checks tenant"| node_google
node_mx_analysis -.->|"resolves records"| node_dns
node_domain_detector -.->|"enriches domains"| node_dns
node_aggressive_api -->|"runs enrichment"| node_aggressive_scan
node_aggressive_api -->|"reads and writes"| node_aggressive_store
node_admin -->|"connects account"| node_oauth
node_oauth -->|"authorizes access"| node_google
node_oauth -->|"registers tenant"| node_tenant_store
node_oauth -->|"encrypts token"| node_security
node_auth -.->|"protects credentials"| node_security
node_report_api -->|"generates report"| node_report_generator
node_report_api -->|"reads results"| node_scan_store
node_onboarding_api -->|"starts scan"| node_engine
node_database -->|"persists"| node_tenant_store
node_database -->|"persists"| node_scan_store
node_database -->|"persists"| node_aggressive_store

click node_app "https://github.com/snifsnsort/mailguard/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/snifsnsort/mailguard/blob/main/frontend/src/utils/api.js"
click node_dashboard "https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/Dashboard.jsx"
click node_checks "https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/Checks.jsx"
click node_history "https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/History.jsx"
click node_lookalike_ui "https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/LookalikeScan.jsx"
click node_api_routes "https://github.com/snifsnsort/mailguard/blob/main/backend/app/main.py"
click node_tenant_api "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/tenants.py"
click node_scan_api "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/scans.py"
click node_report_api "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/reports.py"
click node_aggressive_api "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/aggressive_scan.py"
click node_onboarding_api "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/onboarding.py"
click node_engine "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/scan_engine.py"
click node_m365_checks "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/graph_client.py"
click node_exchange_checks "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/exchange_checker.py"
click node_mx_analysis "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/mx_analyzer.py"
click node_gws_checks "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/google_workspace_checker.py"
click node_domain_detector "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/lookalike_detector.py"
click node_aggressive_scan "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/aggressive_lookalike.py"
click node_report_generator "https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/report_generator.py"
click node_oauth "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/google_auth.py"
click node_auth "https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/auth.py"
click node_security "https://github.com/snifsnsort/mailguard/blob/main/backend/app/core/security.py"
click node_tenant_store "https://github.com/snifsnsort/mailguard/blob/main/backend/app/models/tenant.py"
click node_scan_store "https://github.com/snifsnsort/mailguard/blob/main/backend/app/models/scan.py"
click node_aggressive_store "https://github.com/snifsnsort/mailguard/blob/main/backend/app/models/aggressive_scan.py"
click node_database "https://github.com/snifsnsort/mailguard/blob/main/backend/app/core/database.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_app,node_api_client,node_dashboard,node_checks,node_history,node_lookalike_ui toneBlue
class node_api_routes,node_tenant_api,node_scan_api,node_report_api,node_aggressive_api,node_onboarding_api toneAmber
class node_engine,node_m365_checks,node_exchange_checks,node_mx_analysis,node_gws_checks,node_domain_detector,node_aggressive_scan,node_report_generator toneMint
class node_oauth,node_auth,node_security toneRose
class node_tenant_store,node_scan_store,node_aggressive_store,node_database,node_admin,node_microsoft,node_google,node_dns toneIndigo
```

## Components

### Dashboard

- [React application](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`
- [Posture dashboard](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Security checks](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/Checks.jsx): `frontend/src/pages/Checks.jsx`
- [Scan history](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/History.jsx): `frontend/src/pages/History.jsx`
- [Lookalike review](https://github.com/snifsnsort/mailguard/blob/main/frontend/src/pages/LookalikeScan.jsx): `frontend/src/pages/LookalikeScan.jsx`

### API workflows

- [API router](https://github.com/snifsnsort/mailguard/blob/main/backend/app/main.py): `backend/app/main.py`
- [Tenant management](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/tenants.py): `backend/app/api/tenants.py`
- [Scan operations](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/scans.py): `backend/app/api/scans.py`
- [PDF reports](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`
- [Lookalike endpoints](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/aggressive_scan.py): `backend/app/api/aggressive_scan.py`
- [Onboarding](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/onboarding.py): `backend/app/api/onboarding.py`

### Security analysis

- [Scan orchestrator](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/scan_engine.py): `backend/app/services/scan_engine.py`
- [M365 checks](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/graph_client.py): `backend/app/services/graph_client.py`
- [Exchange checks](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/exchange_checker.py): `backend/app/services/exchange_checker.py`
- [MX analysis](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/mx_analyzer.py): `backend/app/services/mx_analyzer.py`
- [Google checks](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/google_workspace_checker.py): `backend/app/services/google_workspace_checker.py`
- [Lookalike detection](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/lookalike_detector.py): `backend/app/services/lookalike_detector.py`
- [Threat enrichment](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/aggressive_lookalike.py): `backend/app/services/aggressive_lookalike.py`
- [Report generation](https://github.com/snifsnsort/mailguard/blob/main/backend/app/services/report_generator.py): `backend/app/services/report_generator.py`

### Tenant connections

- [Google OAuth](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/google_auth.py): `backend/app/api/google_auth.py`
- [Authentication](https://github.com/snifsnsort/mailguard/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Token encryption](https://github.com/snifsnsort/mailguard/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Persistence

- [Tenant records](https://github.com/snifsnsort/mailguard/blob/main/backend/app/models/tenant.py): `backend/app/models/tenant.py`
- [Scan records](https://github.com/snifsnsort/mailguard/blob/main/backend/app/models/scan.py): `backend/app/models/scan.py`
- [Threat scan records](https://github.com/snifsnsort/mailguard/blob/main/backend/app/models/aggressive_scan.py): `backend/app/models/aggressive_scan.py`
- [Database access](https://github.com/snifsnsort/mailguard/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Tenant admin**
- **Microsoft 365**
- **Google Workspace**
- **Public DNS**

## Connections

- Tenant admin → React application: uses
- React application → API client: requests data (evidence: `frontend/src/App.jsx`)
- React application → Posture dashboard: renders (evidence: `frontend/src/App.jsx`)
- React application → Security checks: routes to (evidence: `frontend/src/App.jsx`)
- React application → Scan history: routes to (evidence: `frontend/src/App.jsx`)
- React application → Lookalike review: routes to (evidence: `frontend/src/App.jsx`)
- API client → API router: calls API
- API router → Tenant management: registers (evidence: `backend/app/main.py`)
- API router → Scan operations: registers (evidence: `backend/app/main.py`)
- API router → PDF reports: registers (evidence: `backend/app/main.py`)
- API router → Lookalike endpoints: registers (evidence: `backend/app/main.py`)
- API router → Onboarding: registers (evidence: `backend/app/main.py`)
- Tenant management → Tenant records: reads and writes (evidence: `backend/app/api/tenants.py`)
- Scan operations → Scan orchestrator: starts scan (evidence: `backend/app/api/scans.py`)
- Scan operations → Scan records: reads and writes (evidence: `backend/app/api/scans.py`)
- Scan orchestrator → M365 checks: queries (evidence: `backend/app/services/scan_engine.py`)
- Scan orchestrator → Exchange checks: queries (evidence: `backend/app/services/scan_engine.py`)
- Scan orchestrator → MX analysis: uses (evidence: `backend/app/services/scan_engine.py`)
- Scan orchestrator → Google checks: queries (evidence: `backend/app/services/scan_engine.py`)
- Scan orchestrator → Lookalike detection: checks domains (evidence: `backend/app/services/scan_engine.py`)
- Scan orchestrator → Scan records: persists results
- M365 checks → Microsoft 365: queries tenant (evidence: `backend/app/services/graph_client.py`)
- Google checks → Google Workspace: checks tenant
- MX analysis → Public DNS: resolves records
- Lookalike detection → Public DNS: enriches domains
- Lookalike endpoints → Threat enrichment: runs enrichment (evidence: `backend/app/api/aggressive_scan.py`)
- Lookalike endpoints → Threat scan records: reads and writes (evidence: `backend/app/api/aggressive_scan.py`)
- Tenant admin → Google OAuth: connects account
- Google OAuth → Google Workspace: authorizes access (evidence: `backend/app/api/google_auth.py`)
- Google OAuth → Tenant records: registers tenant (evidence: `backend/app/api/google_auth.py`)
- Google OAuth → Token encryption: encrypts token (evidence: `backend/app/api/google_auth.py`)
- Authentication → Token encryption: protects credentials
- PDF reports → Report generation: generates report (evidence: `backend/app/api/reports.py`)
- PDF reports → Scan records: reads results (evidence: `backend/app/api/reports.py`)
- Onboarding → Scan orchestrator: starts scan (evidence: `backend/app/api/onboarding.py`)
- Database access → Tenant records: persists (evidence: `backend/app/core/database.py`)
- Database access → Scan records: persists (evidence: `backend/app/core/database.py`)
- Database access → Threat scan records: persists (evidence: `backend/app/core/database.py`)
