# lucia-auth/example-nextjs-email-password-2fa architecture

> Architecture diagram of the GitHub repository lucia-auth/example-nextjs-email-password-2fa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucia-auth/example-nextjs-email-password-2fa
- Repository: https://github.com/lucia-auth/example-nextjs-email-password-2fa

## Overview

##### Main Components

A. Client-Side (Frontend) Layer:
- Authentication Pages Module
- Login
- Signup
- Password Reset Flow
- Email Verification
- 2FA Management
- Settings
- Server Actions (Next.js)

B. Server-Side Layer:
- Authentication Services
- Security Services
- Database Layer
- Email Service

##### Component Details and Relationships

A. Authentication Flow Components:
**┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐**
- Client Pages   │ ──> │  Server Actions  │ ──> │ Auth Services  │
- ┘     └──────────────────┘     └────────────────┘

B. Security Services Layer:
**┌────────────────┐**
- Rate Limiting  │
- ┤
- Encryption   │
- ┤
- Password Check │
- ┘

##### Key Interactions to Highlight

**User Request -> Rate Limiter -> Authentication -> Database**
- ↓
- Email Service
- ↓
- HaveIBeenPwned API

##### Specific Implementation Details

A. Authentication Flows:
**Login Flow:**
**Email/Password -> Rate Limit Check -> Auth Validation -> 2FA (if enabled)**

**Password Reset Flow:**
**Request -> Email Verification -> 2FA Check -> Reset**

**2FA Setup Flow:**
**TOTP Setup -> Recovery Codes Generation -> Verification**

B. Security Measures:
- Rate limiting (using JavaScript Map)
- Email verification
- TOTP-based 2FA
- Recovery codes
- Password validation
- Session management

##### Technical Stack Elements

- Next.js (App Router)
- SQLite Database
- Server Actions
- Email Service (Console Logger)

##### Important Notes

- A note about email simulation (console logging)
- Rate limiting implementation
- Potential areas for improvement (transactions, IP handling)
- Security boundaries

##### Implementation Details

**┌─────────────────────────────────────────┐**
- Client Layer               │
- ┌─────────┐ ┌────────┐ ┌───────────┐  │
- Login  │ │ Signup │ │ Password  │  │
- ┘ └────────┘ │  Reset    │  │
- ┬──────────┴───────────────┘
- ↓
**┌─────────────────────────────────────────┐**
- Security Layer               │
- ┌─────────┐ ┌────────┐ ┌───────────┐  │
- Rate   │ │  2FA   │ │ Password  │  │
- Limiter │ │ TOTP   │ │  Check    │  │
- ┘ └────────┘ └───────────┘  │
- ┬──────────────────────────┘
- ↓
**┌─────────────────────────────────────────┐**
- Storage Layer                │
- ┌─────────────────┐ ┌───────────────┐  │
- SQLite      │ │   Sessions    │  │
- ┘ └───────────────┘  │
- ┘

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        direction TB
        Login["Login Page"]
        Signup["Signup Page"]
        Reset["Password Reset"]
        Verify["Email Verification"]
        TwoFA["2FA Management"]
        Settings["Settings Page"]
    end

    subgraph Actions["Server Actions Layer"]
        direction TB
        LoginAct["Login Actions"]
        SignupAct["Signup Actions"]
        ResetAct["Reset Actions"]
        TwoFAAct["2FA Actions"]
        SettingsAct["Settings Actions"]
    end

    subgraph Security["Security Services"]
        direction TB
        RateLimit["Rate Limiting"]
        Encrypt["Encryption"]
        PassCheck["Password Check"]
        Session["Session Management"]
    end

    subgraph Auth["Authentication Services"]
        direction TB
        TwoFAServ["2FA Service"]
        UserServ["User Service"]
        EmailVerify["Email Verification"]
        PassReset["Password Reset Service"]
    end

    subgraph Storage["Storage Layer"]
        direction TB
        DB[(Database)]
        Schema[("Schema")]
    end

    subgraph Infrastructure["Core Infrastructure"]
        direction TB
        Middle["Middleware"]
        ReqHandle["Request Handler"]
        Utils["Utilities"]
    end

    Email["Email Service"]
    HaveIPwned["HaveIBeenPwned API"]

    %% Connections
    Login --> LoginAct
    Signup --> SignupAct
    Reset --> ResetAct
    TwoFA --> TwoFAAct
    Settings --> SettingsAct

    LoginAct & SignupAct & ResetAct & TwoFAAct & SettingsAct --> RateLimit
    RateLimit --> Auth
    Auth --> DB
    Auth --> Email
    Auth --> HaveIPwned

    %% Click events
    click Login "https://github.com/lucia-auth/example-nextjs-email-password-2fa/tree/main/app/login"
    click Signup "https://github.com/lucia-auth/example-nextjs-email-password-2fa/tree/main/app/signup"
    click Reset "https://github.com/lucia-auth/example-nextjs-email-password-2fa/tree/main/app/reset-password"
    click Verify "https://github.com/lucia-auth/example-nextjs-email-password-2fa/tree/main/app/verify-email"
    click TwoFA "https://github.com/lucia-auth/example-nextjs-email-password-2fa/tree/main/app/2fa"
    click Settings "https://github.com/lucia-auth/example-nextjs-email-password-2fa/tree/main/app/settings"
    
    click LoginAct "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/app/login/actions.ts"
    click SignupAct "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/app/signup/actions.ts"
    click ResetAct "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/app/reset-password/actions.ts"
    click TwoFAAct "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/app/2fa/actions.ts"
    click SettingsAct "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/app/settings/actions.ts"
    
    click RateLimit "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/rate-limit.ts"
    click Encrypt "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/encryption.ts"
    click PassCheck "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/password.ts"
    click Session "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/session.ts"
    
    click TwoFAServ "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/2fa.ts"
    click UserServ "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/user.ts"
    click EmailVerify "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/email-verification.ts"
    click PassReset "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/password-reset.ts"
    
    click DB "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/db.ts"
    click Schema "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/setup.sql"
    
    click Email "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/email.ts"
    
    click Middle "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/middleware.ts"
    click ReqHandle "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/request.ts"
    click Utils "https://github.com/lucia-auth/example-nextjs-email-password-2fa/blob/main/lib/server/utils.ts"

    %% Styling
    classDef client fill:#a8d1ff
    classDef security fill:#ff9999
    classDef auth fill:#90EE90
    classDef storage fill:#d3d3d3
    classDef external fill:#ffeb99
    classDef email fill:#DDA0DD
    classDef infrastructure fill:#DEB887

    class Login,Signup,Reset,Verify,TwoFA,Settings client
    class RateLimit,Encrypt,PassCheck,Session security
    class TwoFAServ,UserServ,EmailVerify,PassReset auth
    class DB,Schema storage
    class HaveIPwned external
    class Email email
    class Middle,ReqHandle,Utils infrastructure
```
