# oscarzhang228/phisherman architecture

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

- Interactive diagram: https://gitdiagram.com/oscarzhang228/phisherman
- Repository: https://github.com/oscarzhang228/phisherman

## Overview

##### Main Components
- Frontend: Built with React (as evidenced by .tsx, .jsx, and configuration files such as vite.config.ts and package.json) and styled with Tailwind CSS. It handles the user interface for interacting with simulations, displaying dashboards, notifications, and training content.
- Backend: Developed with Python (using Flask, based on the file structure with app.py, routes.py, models.py, etc.) and connects to a MongoDB database (as mentioned in the README) to manage user data and simulation results.
- AI Simulation Models: Though not explicitly visible in the file tree, the README explains integration with advanced AI agents (using GPT and similar techniques) for generating phishing and deepfake content.
- Database: MongoDB is referenced in the README as the database for storing user information and simulation metrics.
- External Services/Integrations: There might be external APIs or services for additional AI capabilities, integration with security training platforms, or analytics (as noted in the roadmap for real-time feedback and expansion plans).

##### Relationships & Interactions
- The Frontend interacts with the Backend via API calls. Clearly indicate HTTP or RESTful API connections between these components.
- The Backend communicates with the MongoDB database for CRUD operations related to simulations and user data.
- The AI simulation module (or service) is invoked from the backend to generate the content for phishing or deepfake scenarios.
- Optionally, illustrate any feedback loop where user performance (from the frontend) is analyzed on the backend to dynamically adjust simulation difficulty.

##### Architectural Patterns and Design Principles
- Separation of concerns is evident: the user interface (frontend) is decoupled from business logic (backend).
- An MVC or similar pattern on the backend could be inferred – routes handle incoming API requests, models manage database interactions, and utility functions support business logic.
- Mentioning scalability and security as key non-functional elements.

##### Relevant Technologies
- Frontend: React, Tailwind CSS, Vite, TypeScript/JavaScript.
- Backend: Python, Flask, and likely RESTful API design.
- Database: MongoDB.
- AI Components: Integration with GPT or similar AI models.
- Development Tools: ESLint, package managers (npm for frontend; pip for backend).

- Including legends or notes that briefly describe each component’s role and how they connect.

##### Being Very Detailed
- Within the backend, you may denote the “routes”, “models”, and “utilities” as sub-components to represent the application’s logic layering.
- Even though some pieces (like AI simulation processing) are abstract, make a node for “AI Engine” and describe its responsibility of generating simulation content.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend (React App)"
        F1["index.html"]:::frontend
        F2["App.tsx"]:::frontend
        F3["Components"]:::frontend
        F4["vite.config.ts"]:::frontend
        F5["package.json"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend (Flask API)"
        B1["app.py"]:::backend
        B2["routes.py"]:::backend
        B3["models.py"]:::backend
        B4["utils.py"]:::backend
    end

    %% External Components
    A1["AI Simulation Module"]:::ai
    DB["Database (MongoDB)"]:::database

    %% Connections between components
    F2 -->|"HTTP_API"| B2
    B2 -->|"CRUD"| DB
    B2 -->|"Generate_Simulations"| A1
    A1 -->|"Simulation_Output"| B2
    B1 -->|"Bootstrap"| B2
    B3 -->|"Data_Schema"| DB
    B2 -->|"User_Feedback"| F2

    %% Click Events for Frontend files
    click F1 "https://github.com/oscarzhang228/phisherman/blob/main/frontend/index.html"
    click F2 "https://github.com/oscarzhang228/phisherman/blob/main/frontend/src/App.tsx"
    click F3 "https://github.com/oscarzhang228/phisherman/tree/main/frontend/src/components/"
    click F4 "https://github.com/oscarzhang228/phisherman/blob/main/frontend/vite.config.ts"
    click F5 "https://github.com/oscarzhang228/phisherman/blob/main/frontend/package.json"

    %% Click Events for Backend files
    click B1 "https://github.com/oscarzhang228/phisherman/blob/main/backend/src/app.py"
    click B2 "https://github.com/oscarzhang228/phisherman/blob/main/backend/src/routes.py"
    click B3 "https://github.com/oscarzhang228/phisherman/blob/main/backend/src/models.py"
    click B4 "https://github.com/oscarzhang228/phisherman/blob/main/backend/src/utils.py"

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef database fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef ai fill:#FFD700,stroke:#000,stroke-width:1px;
```
