# alqasmii/zeropass-auth architecture

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

- Interactive diagram: https://gitdiagram.com/alqasmii/zeropass-auth
- Repository: https://github.com/alqasmii/zeropass-auth

## Overview

##### Project type and purpose
- This is a small Node.js-based “magic link” authentication plugin (ZeroPass Auth) meant to be installed into Bubble applications.
- Its purpose is to eliminate passwords by generating one-time login links, emailing them to users, and verifying them on click.

##### File structure
- Top‐level files:
- index.js – the entry point that exposes the plugin’s API endpoints (e.g., requestMagicLink, verifyMagicLink).
- generateToken.js – encapsulates logic to create, sign, and store a one‐time token.
- package.json / package-lock.json – Node.js dependencies.
- node_modules – installed libraries (e.g., JWT, email-sending SDK).
- No dedicated “src” or “lib” directories, but the two JS files separate concerns (API vs. token logic).
- No database code here, implying reliance on an external persistence service (e.g., Redis, DynamoDB) or Bubble’s built-in database.

##### README for additional insights
- Describes plugin features: secure magic link via email, improved security & user experience.

- Layer 1 (Frontend): Bubble App UI.
- Layer 2 (Backend API): index.js endpoints → calls generateToken.js.
- Layer 3 (Data): Persistence Store for tokens.
- Layer 4 (External): Email Provider → end‐user.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Bubble Host Application"
        direction TB
        BubbleUI["Bubble App UI"]:::external
    end

    %% Backend Layer
    subgraph "ZeroPass Auth Service"
        direction TB
        MagicAPI["Magic Link API<br/>(index.js)"]:::ownedService
        TokenService["Token Service<br/>(generateToken.js)"]:::ownedService
    end

    %% Data Layer
    Persistence["Persistence Store<br/>(Redis/DynamoDB)"]:::db

    %% Third-Party Services
    subgraph "External Services"
        direction TB
        EmailProv["Email Provider<br/>(SendGrid/SES)"]:::email
        EmailClient["User Email Client"]:::external
    end

    %% Project Files
    subgraph "Project Files" 
        direction TB
        package["package.json"]:::doc
        lock["package-lock.json"]:::doc
        modules["node_modules"]:::doc
        readme["README.md"]:::doc
    end

    %% Flow Connections
    BubbleUI -->|"POST /requestMagicLink"| MagicAPI
    MagicAPI -->|"generateToken()"| TokenService
    TokenService -->|"storeToken(token)"| Persistence
    TokenService -->|"sendEmail(token)"| EmailProv
    EmailProv -->|"deliver email(link)"| EmailClient
    EmailClient -->|"click magic link"| MagicAPI
    MagicAPI -->|"validateToken() / readToken(token)"| Persistence
    MagicAPI -->|"authCallback"| BubbleUI

    %% Click Events
    click MagicAPI "https://github.com/alqasmii/zeropass-auth/blob/main/index.js"
    click TokenService "https://github.com/alqasmii/zeropass-auth/blob/main/generateToken.js"
    click package "https://github.com/alqasmii/zeropass-auth/blob/main/package.json"
    click lock "https://github.com/alqasmii/zeropass-auth/blob/main/package-lock.json"
    click modules "https://github.com/alqasmii/zeropass-auth/tree/main/node_modules"
    click readme "https://github.com/alqasmii/zeropass-auth/blob/main/README.md"

    %% Styles
    classDef ownedService fill:#D0E8FF,stroke:#0366d6;
    classDef db fill:#D0F0C0,stroke:#228B22;
    classDef external fill:#F5F5F5,stroke:#888;
    classDef email fill:#FFEBCD,stroke:#FFA500;
    classDef doc fill:#FFF2CC,stroke:#D6B656;
```
