# rickyyuan07/phantompen architecture

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

- Interactive diagram: https://gitdiagram.com/rickyyuan07/phantompen
- Repository: https://github.com/rickyyuan07/phantompen

## Overview

##### Main Components
- User Input / Signature Drawing Module: This includes the GUI components provided by scripts like simple_draw.py (for collecting new signature samples) and simple_gui.py (for interactive authentication). These modules are responsible for capturing the user’s drawn signature using the touch interface.
- Core Application / Authentication Logic: The main.py script and authenticator.py implement the business logic for signature verification. They handle user inputs (e.g., username, drawn signature) and orchestrate the flow between the UI and the machine learning model.
- Machine Learning & Model Module: The Siamese network model (evident from siamese_signature_model.pth) is the heart of the signature similarity testing. Related scripts like signature similarity.py and signature_similarity_test.py implement model evaluation and similarity calculation.
- Training and Data Preprocessing Module: The training process is managed by train.py along with the data manipulation script (append_npy_data.py) under the signatures directory. The directory structure under signatures—with separate “train” and “val” folders and further subdivision into "fake" and "real" samples for multiple users (colleen, daniel, ricky, etc.)—highlights the data collection and classification strategy.
- Data Storage / Dataset Organization: The structured dataset (a mix of .npy files for signatures) under the signatures directory indicates how raw signature data is stored, segmented by training and validation, as well as by real versus fake examples.

##### Relationships and Interactions
- During Signature Collection, the drawing application (simple_draw.py) provides an interactive interface. Once the user saves a signature, the canvas data is converted and stored (perhaps as numpy arrays) in the appropriate folder under the signatures tree.
- For authentication, the main.py script triggers the process, where the drawn signature is sent to the authenticator.py module. This module communicates with the machine learning component (loading siamese_signature_model.pth) to compare the current signature with enrolled samples.
- The training pipeline (train.py) uses data from signatures/train (organized by identity and type – fake vs. real) to improve or validate the ML model. The append_npy_data.py script likely assists in preprocessing or aggregating signature data.
- There’s also a testing phase (as seen in signature_similarity_test.py) to validate the similarity matching logic.

##### Architectual Patterns and Design Principles
- Separation of Concerns: The project separates signature collection, authentication, training, and testing into distinct scripts and modules.
- Data Flow Pipeline: A linear yet iterative data flow exists that goes from user input (via UI) → data preprocessing → machine learning inference → authentication response.
- Modular Design: Each major functionality (collection, training, authentication, testing) is encapsulated in separate components, enabling easier debugging and future extensibility.
- Model-Oriented Architecture: The utilization of a pretrained Siamese network encapsulates the ML logic as a distinct “service” or module which the authentication process calls.

##### Relevant Technologies & Frameworks
- Python 3.6+ – as specified in the README.
- Likely PyTorch (or a similar framework) for the Siamese network, indicated by the .pth model file.
- NumPy for signature data processing (.npy files).
- GUI toolkits (potentially Tkinter, Pygame, or another Python library) for the signature drawing interfaces.

- Another branch or module that handles “Signature Enrollment / Data Storage” linking the UI to a “Dataset Repository” (which reflects the signatures directory organization).
- A separate “Training Module” that pulls data from the dataset and updates or validates the ML model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Subgraph
    subgraph "User Interface"
        draw["simple_draw.py"]:::ui
        gui["simple_gui.py"]:::ui
    end

    %% Authentication Engine Subgraph
    subgraph "Authentication Engine"
        main["main.py"]:::core
        auth["authenticator.py"]:::core
    end

    %% ML Model – Siamese Network Subgraph
    subgraph "ML Model – Siamese Network"
        model["siamese_signature_model.pth"]:::ml
        sim["signature similarity.py"]:::ml
        simtest["signature_similarity_test.py"]:::ml
    end

    %% Dataset Repository Node
    repo["signatures"]:::repository

    %% Training & Data Preprocessing Pipeline Subgraph
    subgraph "Training & Data Preprocessing Pipeline"
        train["train.py"]:::training
        append["signatures/append_npy_data.py"]:::training
    end

    %% Connections
    draw -->|"signature_data"| main
    gui -->|"signature_data"| main

    main -->|"model_inference"| model
    auth -->|"model_inference"| model

    draw -->|"enroll_signature"| repo
    gui -->|"enroll_signature"| repo

    repo -->|"training_data"| train
    repo -->|"training_data"| append

    train -->|"model_update"| model
    append -->|"model_update"| model

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ml fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef training fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef repository fill:#F5DEB3,stroke:#000,stroke-width:1px;

    %% Click Events
    click draw "https://github.com/rickyyuan07/phantompen/blob/main/simple_draw.py"
    click gui "https://github.com/rickyyuan07/phantompen/blob/main/simple_gui.py"
    click main "https://github.com/rickyyuan07/phantompen/blob/main/main.py"
    click auth "https://github.com/rickyyuan07/phantompen/blob/main/authenticator.py"
    click model "https://github.com/rickyyuan07/phantompen/blob/main/siamese_signature_model.pth"
    click sim "https://github.com/rickyyuan07/phantompen/blob/main/signature similarity.py"
    click simtest "https://github.com/rickyyuan07/phantompen/blob/main/signature_similarity_test.py"
    click train "https://github.com/rickyyuan07/phantompen/blob/main/train.py"
    click append "https://github.com/rickyyuan07/phantompen/blob/main/signatures/append_npy_data.py"
    click repo "https://github.com/rickyyuan07/phantompen/tree/main/signatures"
```
