# aryakhot/ethosguard architecture

> Architecture diagram of the GitHub repository aryakhot/ethosguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryakhot/ethosguard
- Repository: https://github.com/aryakhot/ethosguard

## Overview

##### Project type and purpose
- EthosGuard is a full-stack, AI-powered cyber threat detection framework with three detection modules (DDoS, Spam, Fraud), a web-based UI (Streamlit/Flask), real-time analytics, and pre-trained ML models.

##### File structure
- Top level
- Home.py – orchestrator/main controller
- ddosattack.sh – DDoS traffic simulator
- gmail_api.py – Email ingestion & spam-detection logic
- preprocessed_data.csv – fraud detection training/test data
- requirements.txt – dependencies
- README.md – documentation
- Directories
- models/ – serialized ML artifacts (RF, XGBoost, stacking, TF-IDF vectorizer, label encoder)
- pages/ – Streamlit/Flask UI components for each module (1_DDoS_Detection.py, 2_Fraud_Detection.py, 3_Spam_Detection.py)

##### README for additional insights
- Modular threat detection: separate DDoS, Spam, Fraud pipelines
- Real-time capabilities: streaming inputs, immediate model inference, alerts
- AI/ML stack: Random Forest, XGBoost, ensemble stacking, SMOTE/ADASYN sampling
- Web interface built on Streamlit or Flask

##### Detailed element checklist
- UI layer showing three pages

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        NT["Network Traffic"]:::external
        EI["Email Inbox"]:::external
        TD["Transaction Data"]:::external
    end

    %% Ingestion & Preprocessing
    subgraph "Ingestion & Preprocessing"
        DDOS_SH["ddosattack.sh"]:::ingest
        GMAIL_API["gmail_api.py"]:::ingest
        PREPROC["preprocessed_data.csv"]:::storage
    end

    %% Orchestrator
    ORCH["Orchestrator (Home.py)"]:::orch

    %% Detection Modules
    subgraph "Detection Modules"
        DDOS_DET["DDoS Detector"]:::inference
        SPAM_DET["Spam Detector"]:::inference
        FRAUD_DET["Fraud Detector"]:::inference
    end

    %% Model Store
    subgraph "Model Store"
        MS_DIR["models/"]:::storage
        M1["stacking_model_ddos_detection.pkl"]:::storage
        M2["stacking_model.pkl"]:::storage
        M3["random_forest_model.pkl"]:::storage
        M4["xgboost_model.pkl"]:::storage
        M5["tfidf_vectorizer.pkl"]:::storage
        M6["label_encoder.pkl"]:::storage
        M7["stacking_model_old.pkl"]:::storage
    end

    %% Web UI
    subgraph "Web UI (Streamlit/Flask Pages)"
        UI1["1_DDoS_Detection.py"]:::ui
        UI2["2_Fraud_Detection.py"]:::ui
        UI3["3_Spam_Detection.py"]:::ui
    end

    %% External Services
    subgraph "External Services"
        GMAIL_EXT["Gmail API"]:::external
    end

    %% Arrows Data Sources to Ingestion
    NT --> DDOS_SH
    EI --> GMAIL_API
    TD --> PREPROC

    %% Ingestion to Orchestrator
    DDOS_SH --> ORCH
    GMAIL_API --> ORCH
    PREPROC --> ORCH

    %% Orchestrator to Detection Modules
    ORCH --> DDOS_DET
    ORCH --> SPAM_DET
    ORCH --> FRAUD_DET

    %% Detection Modules to Model Store
    DDOS_DET --> M1
    DDOS_DET --> M2
    DDOS_DET --> M3
    DDOS_DET --> M4
    SPAM_DET --> M5
    SPAM_DET --> M6
    FRAUD_DET --> M2
    FRAUD_DET --> M3
    FRAUD_DET --> M4
    FRAUD_DET --> M7

    %% Orchestrator to UI
    ORCH --> UI1
    ORCH --> UI2
    ORCH --> UI3

    %% External service for spam
    GMAIL_EXT --> GMAIL_API

    %% Click Events
    click ORCH "https://github.com/aryakhot/ethosguard/blob/main/Home.py"
    click DDOS_SH "https://github.com/aryakhot/ethosguard/blob/main/ddosattack.sh"
    click GMAIL_API "https://github.com/aryakhot/ethosguard/blob/main/gmail_api.py"
    click PREPROC "https://github.com/aryakhot/ethosguard/blob/main/preprocessed_data.csv"
    click MS_DIR "https://github.com/aryakhot/ethosguard/tree/main/models/"
    click M1 "https://github.com/aryakhot/ethosguard/blob/main/models/stacking_model_ddos_detection.pkl"
    click M2 "https://github.com/aryakhot/ethosguard/blob/main/models/stacking_model.pkl"
    click M3 "https://github.com/aryakhot/ethosguard/blob/main/models/random_forest_model.pkl"
    click M4 "https://github.com/aryakhot/ethosguard/blob/main/models/xgboost_model.pkl"
    click M5 "https://github.com/aryakhot/ethosguard/blob/main/models/tfidf_vectorizer.pkl"
    click M6 "https://github.com/aryakhot/ethosguard/blob/main/models/label_encoder.pkl"
    click M7 "https://github.com/aryakhot/ethosguard/blob/main/models/stacking_model_old.pkl"
    click UI1 "https://github.com/aryakhot/ethosguard/blob/main/pages/1_DDoS_Detection.py"
    click UI2 "https://github.com/aryakhot/ethosguard/blob/main/pages/2_Fraud_Detection.py"
    click UI3 "https://github.com/aryakhot/ethosguard/blob/main/pages/3_Spam_Detection.py"

    %% Styles
    classDef ingest fill:#8dd3c7,stroke:#333,stroke-width:1px
    classDef inference fill:#b2df8a,stroke:#333,stroke-width:1px
    classDef storage fill:#ffffb3,stroke:#333,stroke-width:1px
    classDef ui fill:#fb8072,stroke:#333,stroke-width:1px
    classDef external fill:#bebada,stroke:#333,stroke-width:1px
    classDef orch fill:#80b1d3,stroke:#333,stroke-width:1px
```
