# alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings architecture

> Architecture diagram of the GitHub repository alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings
- Repository: https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings

## Overview

Show Your Workfin is a Streamlit phishing-risk checker for school staff. A user pastes an email, the app separates any message headers, builds model features, predicts a risk score, and presents warning signs and practical advice. Its optional authentication check reads SPF, DKIM, and DMARC results from pasted headers; it does not contact mail servers or retain pasted text. The README also documents a research workflow for assembling data, cleaning it, training models, and evaluating generalisation. Notebook details are based on README descriptions, not inspected notebook source.

Main entry points: [`app/app.py`](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py) (Analysis workflow), [`notebooks/04_training_models.ipynb`](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/04_training_models.ipynb) (Model training), [`notebooks/05_models_evaluate.ipynb`](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/05_models_evaluate.ipynb) (Model evaluation), [`notebooks/01_data_download.ipynb`](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/01_data_download.ipynb) (Data acquisition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_streamlit_ui["Paste interface<br/>[app.py]"]
  node_results_view["Risk and advice<br/>[app.py]"]
end

subgraph group_runtime["Email analysis"]
  node_analysis["Analysis workflow<br/>[app.py]"]
  node_headers["Header checks<br/>[app.py]"]
  node_features["Text features<br/>[features.py]"]
  node_classifier["Risk classifier"]
  node_explanations["Warning signs<br/>[app.py]"]
end

subgraph group_research["Model research"]
  node_download["Data acquisition"]
  node_explore["Data exploration"]
  node_clean["Data cleaning"]
  node_train["Model training"]
  node_evaluate["Model evaluation"]
end

subgraph group_evidence["Data and evaluation"]
  node_corpora[("Public email corpora<br/>[README.md]")]
  node_synthetic_test[("Synthetic test emails")]
  node_demo_data[("Demo examples<br/>[demo_dataset.csv]")]
  node_evaluation_outputs["Evaluation results<br/>[README.md]"]
end

node_staff(("School staff"))

node_staff -->|"pastes email"| node_streamlit_ui
node_streamlit_ui -->|"submits text"| node_analysis
node_analysis -->|"splits headers"| node_headers
node_analysis -->|"builds features"| node_features
node_analysis -->|"requests score"| node_classifier
node_analysis -->|"builds reasons"| node_explanations
node_analysis -->|"renders result"| node_results_view
node_download -->|"downloads data"| node_corpora
node_download -->|"feeds data"| node_explore
node_explore -->|"informs cleaning"| node_clean
node_clean -->|"provides cleaned data"| node_train
node_train -->|"writes model"| node_classifier
node_train -->|"writes feature code"| node_features
node_train -->|"supports evaluation"| node_evaluate
node_synthetic_test -->|"tests model"| node_evaluate
node_demo_data -->|"scores examples"| node_evaluate
node_evaluate -->|"records metrics"| node_evaluation_outputs

click node_streamlit_ui "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py"
click node_analysis "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py"
click node_headers "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py"
click node_features "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/model/features.py"
click node_classifier "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/model/phishing_model.joblib"
click node_explanations "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py"
click node_results_view "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py"
click node_download "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/01_data_download.ipynb"
click node_explore "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/02_data_explore.ipynb"
click node_clean "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/03_data_clean.ipynb"
click node_train "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/04_training_models.ipynb"
click node_evaluate "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/05_models_evaluate.ipynb"
click node_corpora "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/data/README.md"
click node_synthetic_test "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/data/synthetic_education_emails.csv"
click node_demo_data "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/data/demo_dataset.csv"
click node_evaluation_outputs "https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/results/README.md"

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_streamlit_ui,node_results_view toneBlue
class node_analysis,node_headers,node_features,node_classifier,node_explanations toneAmber
class node_download,node_explore,node_clean,node_train,node_evaluate toneMint
class node_corpora,node_synthetic_test,node_demo_data,node_evaluation_outputs toneRose
class node_staff toneIndigo
```

## Components

### User interface

- [Paste interface](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py): `app/app.py`
- [Risk and advice](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py): `app/app.py`

### Email analysis

- [Analysis workflow](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py): `app/app.py`
- [Header checks](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py): `app/app.py`
- [Text features](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/model/features.py): `app/model/features.py`
- [Risk classifier](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/model/phishing_model.joblib): `app/model/phishing_model.joblib`
- [Warning signs](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/app/app.py): `app/app.py`

### Model research

- [Data acquisition](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/01_data_download.ipynb): `notebooks/01_data_download.ipynb`
- [Data exploration](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/02_data_explore.ipynb): `notebooks/02_data_explore.ipynb`
- [Data cleaning](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/03_data_clean.ipynb): `notebooks/03_data_clean.ipynb`
- [Model training](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/04_training_models.ipynb): `notebooks/04_training_models.ipynb`
- [Model evaluation](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/notebooks/05_models_evaluate.ipynb): `notebooks/05_models_evaluate.ipynb`

### Data and evaluation

- [Public email corpora](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/data/README.md): `data/README.md`
- [Synthetic test emails](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/data/synthetic_education_emails.csv): `data/synthetic_education_emails.csv`
- [Demo examples](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/data/demo_dataset.csv): `data/demo_dataset.csv`
- [Evaluation results](https://github.com/alexercsei-code/showyourworkfin-a-phishing-email-detection-tool-for-educational-settings/blob/main/results/README.md): `results/README.md`

### Other components

- **School staff**

## Connections

- School staff → Paste interface: pastes email
- Paste interface → Analysis workflow: submits text
- Analysis workflow → Header checks: splits headers
- Analysis workflow → Text features: builds features
- Analysis workflow → Risk classifier: requests score
- Analysis workflow → Warning signs: builds reasons
- Analysis workflow → Risk and advice: renders result
- Data acquisition → Public email corpora: downloads data
- Data acquisition → Data exploration: feeds data
- Data exploration → Data cleaning: informs cleaning
- Data cleaning → Model training: provides cleaned data
- Model training → Risk classifier: writes model
- Model training → Text features: writes feature code
- Model training → Model evaluation: supports evaluation
- Synthetic test emails → Model evaluation: tests model
- Demo examples → Model evaluation: scores examples
- Model evaluation → Evaluation results: records metrics