Authentication Module Overview

Summary

The Authentication module provides comprehensive user authentication and authorization capabilities for the Trend Viewer API. It supports multiple authentication methods including email/password login, Google OAuth, and standard email authentication, along with user registration, password reset, and session management.

Overview Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components
    Client[Client Application]
    AuthController[AuthController]
    AuthService(AuthService)
    UserDB[(users)]
    RoleDB[(roles)]
    SessionDB[(sessions)]

    Client --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>Send authentication request</p>
        </div>
    ]
    Step1 --> AuthController

    AuthController --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>Validate request</p>
        </div>
    ]
    Step2 --> AuthService

    AuthService --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>Authenticate user</p>
        </div>
    ]
    Step3 --> UserDB

    AuthService --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>Check user roles</p>
        </div>
    ]
    Step4 --> RoleDB

    AuthService --- Step5[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
            <p style='margin-top: 8px'>Create session</p>
        </div>
    ]
    Step5 --> SessionDB

    AuthService --- Step6[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6</span>
            <p style='margin-top: 8px'>Create auth cookies</p>
        </div>
    ]
    Step6 --> AuthController

    AuthController --- Step7[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>7</span>
            <p style='margin-top: 8px'>Return response</p>
        </div>
    ]
    Step7 --> Client

    %% Styling
    style Client fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AuthController fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AuthService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style UserDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style RoleDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style SessionDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5 fill:transparent,stroke:transparent,stroke-width:1px
    style Step6 fill:transparent,stroke:transparent,stroke-width:1px
    style Step7 fill:transparent,stroke:transparent,stroke-width:1px

Database Related Tables & Fields

erDiagram
    users {
        bigint id PK "Primary key"
        varchar name "User's full name"
        varchar email UK "User's email address (unique)"
        varchar payment_provider_customer_id "Payment provider customer ID"
        tinyint status "User status (1: active, 0: inactive)"
        varchar remember_token "Laravel remember token"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp"
        timestamp deleted_at "Soft delete timestamp"
        boolean is_first_login "First login flag"
    }
    
    groups {
        bigint id PK "Primary key"
        varchar name "Group name"
        text description "Group description"
        bigint created_by FK "User who created the group"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp"
    }
    
    group_members {
        bigint id PK "Primary key"
        bigint group_id FK "Group ID"
        bigint user_id FK "User ID"
        bigint group_role_id FK "Role ID in the group"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp"
    }
    
    group_roles {
        bigint id PK "Primary key"
        varchar name "Role name"
        text description "Role description"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp"
    }
    
    users ||--o{ group_members : "has"
    groups ||--o{ group_members : "contains"
    group_roles ||--o{ group_members : "defines"
    users ||--o{ groups : "creates"

Module Features

Additional Notes

• Standard Authentication: The system uses standard email/password authentication with secure validation
• Multi-tenant Support: Users can belong to multiple groups with different roles
• Session Management: Comprehensive session handling with IP tracking and user agent logging
• Rate Limiting: Implemented for security on authentication endpoints
• Soft Deletes: User accounts are soft-deleted for data integrity
• First Login Tracking: Special handling for first-time user experiences
• Email Verification: Registration includes email verification for enhanced security