# perseidesjs/auth-otp architecture

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

- Interactive diagram: https://gitdiagram.com/perseidesjs/auth-otp
- Repository: https://github.com/perseidesjs/auth-otp

## Overview

##### Project type and purpose
- This is a Medusa 2.x plugin written in TypeScript that adds OTP (One-Time Password)–based authentication to a Medusa backend.
- The README and file structure confirm it’s a backend-only plugin, exposing HTTP routes under `src/api` and encapsulating OTP generation and verification workflows.

##### File structure
- Top-level files:
- `.github`, CI/CD workflows, `package.json`, `tsconfig.json` – typical for an NPM package.
- `src/` – main code.
- `integration-tests/` – automated tests.
- Under `src/`:
- `api/` – HTTP route definitions for OTP operations: generate, pre-register, verify.
- `providers/otp/` – abstraction and implementation of the OTP service (e.g. sending SMS or email).
- `workflows/` – business logic orchestrating multiple steps: fetching actors, validating, storing, sending OTP, verifying.
- `utils/` and `types/` – shared helpers and TypeScript types.
- `middlewares.ts` – Express-style middleware for Medusa routes.
- No “frontend” or UI code – it plugs into the Medusa server process.

##### README for additional insights
- Confirms plugin purpose: “Implement seamlessly OTP-based authentication for Medusa 2.x.”

##### Detail without overthinking
- Break out every folder as a component if it clarifies responsibilities (e.g., separate “Validators” under Middleware).
- Both “happy path” and error/validation flows if space permits.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::client
    subgraph "Medusa Server"
        direction TB
        PluginContainer["Auth-OTP Plugin"]:::plugin
        subgraph "Auth-OTP Plugin"
            direction TB
            subgraph "API Layer"
                direction TB
                GenOTPRoute["Generate OTP Route"]:::api
                GenValidators["Generate OTP Validators"]:::api
                PreRegRoute["Pre-register OTP Route"]:::api
                PreRegValidators["Pre-register Validators"]:::api
                VerRoute["Verify OTP Route"]:::api
                VerValidators["Verify OTP Validators"]:::api
            end
            Middleware["Middleware for Medusa Routes"]:::middleware
            subgraph "Workflow Engine"
                direction TB
                WFEntry["Workflow Engine Entry"]:::workflow
                GenWF["Generate OTP Workflow"]:::workflow
                PreRegWF["Pre-register Check Workflow"]:::workflow
                VerWF["Verify OTP Workflow"]:::workflow
                subgraph "Workflow Steps"
                    direction TB
                    StepGetActor["Get Actor Step"]:::workflow
                    StepGetAuthID["Get Auth Identity Step"]:::workflow
                    StepGenOTP["Generate OTP Step"]:::workflow
                    StepStoreOTP["Store/Retrieve OTP Step"]:::workflow
                    StepPreRegChk["Pre-register Existence Check Step"]:::workflow
                    StepValOTP["Validate OTP Step"]:::workflow
                end
            end
            subgraph "OTP Provider"
                direction TB
                ProviderAbstr["Provider Abstraction"]:::provider
                ProviderImpl["Provider Implementation (SMS/Email)"]:::provider
            end
            subgraph "Utils & Types"
                direction TB
                UtilsOpt["Plugin Options Loader"]:::utils
                UtilsOTP["OTP Helpers"]:::utils
                Types["Type Definitions"]:::types
            end
        end
    end
    DB["Medusa Database"]:::db
    ExtService["SMS/Email Service"]:::external

    Client -->|"HTTP Request"| PluginContainer
    PluginContainer -->|"route →"| GenOTPRoute
    GenOTPRoute -->|validation| GenValidators
    GenOTPRoute -->|middleware| Middleware
    GenValidators -->|invoke| WFEntry
    Middleware -->|invoke| WFEntry
    WFEntry -->|start generate| GenWF
    GenWF -->|step| StepGetActor
    GenWF -->|step| StepGetAuthID
    GenWF -->|step| StepGenOTP
    GenWF -->|step| StepStoreOTP
    StepStoreOTP -->|persist| DB
    StepGenOTP -->|use| ProviderAbstr
    ProviderAbstr -->|delegate| ProviderImpl
    ProviderImpl -->|send OTP| ExtService
    ExtService -->|response| ProviderImpl
    ProviderImpl -->|return| WFEntry

    %% Click Events
    click GenOTPRoute "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/auth/[actor_type]/otp/generate/route.ts"
    click GenValidators "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/auth/[actor_type]/otp/generate/validators.ts"
    click PreRegRoute "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/auth/[actor_type]/otp/pre-register/route.ts"
    click PreRegValidators "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/auth/[actor_type]/otp/pre-register/validators.ts"
    click VerRoute "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/auth/[actor_type]/otp/verify/route.ts"
    click VerValidators "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/auth/[actor_type]/otp/verify/validators.ts"
    click Middleware "https://github.com/perseidesjs/auth-otp/blob/develop/src/api/middlewares.ts"
    click WFEntry "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/index.ts"
    click GenWF "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/generate-otp.ts"
    click PreRegWF "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/pre-register-check.ts"
    click VerWF "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/verify-otp.ts"
    click StepGetActor "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/steps/get-actor-step.ts"
    click StepGetAuthID "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/steps/get-auth-identity-step.ts"
    click StepGenOTP "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/steps/generate-otp-step.ts"
    click StepStoreOTP "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/steps/get-stored-otp-step.ts"
    click StepPreRegChk "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/steps/pre-register-check-actor-existence.ts"
    click StepValOTP "https://github.com/perseidesjs/auth-otp/blob/develop/src/workflows/steps/validate-otp-step.ts"
    click ProviderAbstr "https://github.com/perseidesjs/auth-otp/blob/develop/src/providers/otp/index.ts"
    click ProviderImpl "https://github.com/perseidesjs/auth-otp/blob/develop/src/providers/otp/services/otp.ts"
    click UtilsOpt "https://github.com/perseidesjs/auth-otp/blob/develop/src/utils/get-plugin-options.ts"
    click UtilsOTP "https://github.com/perseidesjs/auth-otp/blob/develop/src/utils/otp.ts"
    click Types "https://github.com/perseidesjs/auth-otp/blob/develop/src/types/index.ts"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef plugin fill:#bbf,stroke:#333,stroke-width:1px
    classDef api fill:#cff,stroke:#333,stroke-width:1px
    classDef middleware fill:#fcf,stroke:#333,stroke-width:1px
    classDef workflow fill:#bfb,stroke:#333,stroke-width:1px
    classDef provider fill:#fbf,stroke:#333,stroke-width:1px
    classDef utils fill:#ffd,stroke:#333,stroke-width:1px
    classDef types fill:#ddf,stroke:#333,stroke-width:1px
    classDef db fill:#fff0f0,stroke:#f66,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#eef,stroke:#66f,stroke-width:2px,stroke-dasharray: 5 5
```
