# apdoescoding18/phishshield architecture

> Architecture diagram of the GitHub repository apdoescoding18/phishshield, 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/apdoescoding18/phishshield
- Repository: https://github.com/apdoescoding18/phishshield

## Overview

PhishShield is a backend portal for submitting email messages for phishing and attachment analysis, then retrieving job status, parsed artifacts, findings, and a risk verdict. The documented workflow is upload → asynchronous analysis → results; the excerpts show parsing, four analyzer types, and risk scoring. The orchestrator owns those analysis calls and persistence. Source-index references identify additional models and modules, but unsampled behavior is not inferred beyond those references.

Main entry points: [`backend/app/workers/orchestrator.py`](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/workers/orchestrator.py) (Analysis orchestrator), [`backend/app/api/v1/endpoints/analyses.py`](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/api/v1/endpoints/analyses.py) (Analysis API), [`backend/app/core/database.py`](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/core/database.py) (Database sessions), [`backend/app/schemas/analyzer.py`](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/schemas/analyzer.py) (Analyzer contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Submission and API"]
  node_api["Analysis API<br/>[analyses.py]"]
  node_upload["Secure upload<br/>[upload.py]"]
end

subgraph group_analysis["Email Analysis"]
  node_parser["Email parser<br/>[parser.py]"]
  node_auth["Auth analyzer<br/>[auth_analyzer.py]"]
  node_content["Content analyzer"]
  node_urls["URL analyzer<br/>[url_analyzer.py]"]
  node_attachments["Attachment analyzer"]
  node_context["Analyzer contracts<br/>[analyzer.py]"]
end

subgraph group_results["Findings and Results"]
  node_riskengine["Risk engine<br/>[risk_engine.py]"]
  node_findings[("Analysis findings<br/>[finding.py]")]
  node_riskresult[("Risk result<br/>[risk.py]")]
end

subgraph group_runtime["Runtime and Storage"]
  node_worker["Analysis orchestrator<br/>[orchestrator.py]"]
  node_analysisdata[("Jobs and artifacts<br/>[analysis.py]")]
  node_audit[("Audit events<br/>[audit.py]")]
  node_database["Database sessions<br/>[database.py]"]
end

node_user(("Email submitter"))
node_broker["Task broker"]

node_user -->|"submits email"| node_api
node_api -->|"stores upload"| node_upload
node_api -->|"enqueues job"| node_worker
node_api -->|"reads job data"| node_analysisdata
node_api -->|"reads findings"| node_findings
node_api -->|"reads verdict"| node_riskresult
node_api -.->|"dispatches task"| node_broker
node_worker -->|"loads and updates"| node_analysisdata
node_worker -->|"parses email"| node_parser
node_worker -->|"runs analyzer"| node_auth
node_worker -->|"runs analyzer"| node_content
node_worker -->|"runs analyzer"| node_urls
node_worker -->|"runs analyzer"| node_attachments
node_worker -->|"persists findings"| node_findings
node_worker -->|"scores findings"| node_riskengine
node_riskengine -->|"persists score"| node_riskresult
node_parser -->|"stores parsed artifacts"| node_analysisdata
node_auth -->|"uses result schemas"| node_context
node_content -.->|"uses result schemas"| node_context
node_urls -.->|"uses result schemas"| node_context
node_attachments -.->|"uses result schemas"| node_context
node_database -->|"provides ORM base"| node_analysisdata
node_database -.->|"provides ORM base"| node_findings
node_database -.->|"provides ORM base"| node_riskresult
node_database -.->|"provides ORM base"| node_audit
node_upload -.->|"records upload event"| node_audit

click node_api "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/api/v1/endpoints/analyses.py"
click node_upload "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/upload.py"
click node_worker "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/workers/orchestrator.py"
click node_parser "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/parser.py"
click node_auth "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/auth_analyzer.py"
click node_content "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/content_analyzer.py"
click node_urls "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/url_analyzer.py"
click node_attachments "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/attachment_analyzer.py"
click node_context "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/schemas/analyzer.py"
click node_riskengine "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/risk_engine.py"
click node_findings "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/finding.py"
click node_riskresult "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/risk.py"
click node_analysisdata "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/analysis.py"
click node_audit "https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/audit.py"
click node_database "https://github.com/apdoescoding18/phishshield/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_api,node_upload toneBlue
class node_parser,node_auth,node_content,node_urls,node_attachments,node_context toneAmber
class node_riskengine,node_findings,node_riskresult toneMint
class node_worker,node_analysisdata,node_audit,node_database,node_broker toneRose
class node_user toneIndigo
```

## Components

### Submission and API

- [Analysis API](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/api/v1/endpoints/analyses.py): `backend/app/api/v1/endpoints/analyses.py`
- [Secure upload](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/upload.py): `backend/app/services/upload.py`

### Email Analysis

- [Email parser](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/parser.py): `backend/app/services/parser.py`
- [Auth analyzer](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/auth_analyzer.py): `backend/app/services/analyzers/auth_analyzer.py`
- [Content analyzer](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/content_analyzer.py): `backend/app/services/analyzers/content_analyzer.py`
- [URL analyzer](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/url_analyzer.py): `backend/app/services/analyzers/url_analyzer.py`
- [Attachment analyzer](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/analyzers/attachment_analyzer.py): `backend/app/services/analyzers/attachment_analyzer.py`
- [Analyzer contracts](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/schemas/analyzer.py): `backend/app/schemas/analyzer.py`

### Findings and Results

- [Risk engine](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/services/risk_engine.py): `backend/app/services/risk_engine.py`
- [Analysis findings](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/finding.py): `backend/app/models/finding.py`
- [Risk result](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/risk.py): `backend/app/models/risk.py`

### Runtime and Storage

- [Analysis orchestrator](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/workers/orchestrator.py): `backend/app/workers/orchestrator.py`
- [Jobs and artifacts](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/analysis.py): `backend/app/models/analysis.py`
- [Audit events](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/models/audit.py): `backend/app/models/audit.py`
- [Database sessions](https://github.com/apdoescoding18/phishshield/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Email submitter**
- **Task broker**

## Connections

- Email submitter → Analysis API: submits email (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis API → Secure upload: stores upload (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis API → Analysis orchestrator: enqueues job (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis API → Jobs and artifacts: reads job data (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis API → Analysis findings: reads findings (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis API → Risk result: reads verdict (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis API → Task broker: dispatches task (evidence: `backend/app/api/v1/endpoints/analyses.py`)
- Analysis orchestrator → Jobs and artifacts: loads and updates (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → Email parser: parses email (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → Auth analyzer: runs analyzer (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → Content analyzer: runs analyzer (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → URL analyzer: runs analyzer (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → Attachment analyzer: runs analyzer (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → Analysis findings: persists findings (evidence: `backend/app/workers/orchestrator.py`)
- Analysis orchestrator → Risk engine: scores findings (evidence: `backend/app/workers/orchestrator.py`)
- Risk engine → Risk result: persists score (evidence: `backend/app/services/risk_engine.py`)
- Email parser → Jobs and artifacts: stores parsed artifacts (evidence: `backend/app/services/parser.py`)
- Auth analyzer → Analyzer contracts: uses result schemas (evidence: `backend/app/services/analyzers/auth_analyzer.py`)
- Content analyzer → Analyzer contracts: uses result schemas (evidence: `backend/app/services/analyzers/content_analyzer.py`)
- URL analyzer → Analyzer contracts: uses result schemas (evidence: `backend/app/services/analyzers/url_analyzer.py`)
- Attachment analyzer → Analyzer contracts: uses result schemas (evidence: `backend/app/services/analyzers/attachment_analyzer.py`)
- Database sessions → Jobs and artifacts: provides ORM base (evidence: `backend/app/models/analysis.py`)
- Database sessions → Analysis findings: provides ORM base (evidence: `backend/app/models/finding.py`)
- Database sessions → Risk result: provides ORM base (evidence: `backend/app/models/risk.py`)
- Database sessions → Audit events: provides ORM base (evidence: `backend/app/models/audit.py`)
- Secure upload → Audit events: records upload event (evidence: `backend/app/services/upload.py`)
