graph TB
    subgraph "Client Layer"
        Client[Client Application]
    end

    subgraph "API Gateway Layer"
        API[Spring Boot API<br/>Port 8080]
        JWKS[JWKS Endpoint<br/>/.well-known/jwks.json]
    end

    subgraph "Service Layer"
        AuthSvc[Authentication Services]
        TokenSvc[Token Services]
        EmailSvc[Email Services]
        OrgSvc[Organization Services]
    end

    subgraph "Security Layer"
        JWT[JWT Service<br/>RS256 Signing]
        Hash[Hashing Service<br/>SHA256/Bcrypt]
        Valid[Validation Service<br/>Redirect URLs]
    end

    subgraph "Data Layer"
        PG[(PostgreSQL<br/>User Data)]
        Redis[(Redis<br/>Tokens & Cache)]
        RMQ[RabbitMQ<br/>Email Queue]
    end

    subgraph "External Services"
        SMTP[SMTP Server]
    end

    Client -->|HTTPS| API
    Client -->|Verify JWT| JWKS

    API --> AuthSvc
    API --> TokenSvc
    API --> OrgSvc

    AuthSvc --> EmailSvc
    AuthSvc --> JWT
    AuthSvc --> Hash
    AuthSvc --> Valid

    TokenSvc --> JWT
    TokenSvc --> Hash

    EmailSvc -->|Enqueue| RMQ
    RMQ -->|Consume| SMTP

    AuthSvc --> PG
    AuthSvc --> Redis
    TokenSvc --> Redis
    OrgSvc --> PG

    style Client fill:#bbdefb,stroke:#1976d2,stroke-width:2px,color:#000
    style API fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style JWKS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style AuthSvc fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style TokenSvc fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style EmailSvc fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style OrgSvc fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style JWT fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,color:#000
    style Hash fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,color:#000
    style Valid fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,color:#000
    style PG fill:#b2dfdb,stroke:#00796b,stroke-width:2px,color:#000
    style Redis fill:#ffccbc,stroke:#d84315,stroke-width:2px,color:#000
    style RMQ fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px,color:#000
    style SMTP fill:#d1c4e9,stroke:#512da8,stroke-width:2px,color:#000

graph LR
    subgraph "Docker Environment"
        subgraph "Application Container"
            App[Suraksha Spring Boot<br/>Port 8080]
        end

        subgraph "Data Containers"
            DB[PostgreSQL<br/>Port 5433]
            Cache[Redis<br/>Port 6379]
            Queue[RabbitMQ<br/>Ports 5672, 15672]
        end
    end

    subgraph "External"
        Client[Client Apps]
        SMTP[Email Provider]
    end

    Client -->|HTTP/HTTPS| App
    App -->|JDBC| DB
    App -->|Redis Protocol| Cache
    App -->|AMQP| Queue
    Queue -->|SMTP| SMTP

    style App fill:#4caf50
    style DB fill:#2196f3
    style Cache fill:#f44336
    style Queue fill:#ff9800
    style Client fill:#9c27b0
    style SMTP fill:#607d8b

graph LR
    subgraph Controllers["Controllers"]
        UC[UserController]
        JC[JwksController]
    end

    subgraph CoreServices["Core Services"]
        LS[LoginService]
        RS[RegistrationService]
        MUS[MagicUrlService]
        TFS[TwoFactorService]
        FPS[ForgotPasswordService]
        RTS[RefreshTokenService]
        LOS[LogoutService]
    end

    subgraph SupportServices["Support Services"]
        JS[JwtService]
        OS[OtpService]
        HS[HashingService]
        HMS[HmacService]
        VRS[ValidRedirectService]
        ETS[EmailTemplateService]
        MSS[MailSenderService]
    end

    subgraph DataAccess["Data Access"]
        UR[UserRepository]
        OR[OrganisationsRepository]
        RTR[RefreshTokenRepository]
    end

    UC --> LS
    UC --> RS
    UC --> MUS
    UC --> TFS
    UC --> FPS
    UC --> RTS
    UC --> LOS
    JC --> JS

    LS --> JS
    LS --> OS
    LS --> HS
    LS --> VRS

    RS --> JS
    RS --> HS

    MUS --> HS
    MUS --> ETS
    MUS --> MSS

    TFS --> OS
    TFS --> ETS
    TFS --> MSS

    FPS --> HS
    FPS --> ETS
    FPS --> MSS

    RTS --> JS
    RTS --> HS

    LS --> UR
    RS --> UR
    MUS --> UR
    FPS --> UR

    RS --> OR
    RTS --> RTR

    style UC fill:#bbdefb,stroke:#1976d2,stroke-width:2px,color:#000
    style JC fill:#bbdefb,stroke:#1976d2,stroke-width:2px,color:#000

    style LS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style RS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style MUS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style TFS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style FPS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style RTS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style LOS fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000

    style JS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style OS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style HS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style HMS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style VRS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style ETS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style MSS fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000

    style UR fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,color:#000
    style OR fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,color:#000
    style RTR fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,color:#000

sequenceDiagram
    participant C as Client
    participant API as Spring Boot API
    participant Auth as LoginService
    participant Hash as HashingService
    participant JWT as JwtService
    participant DB as PostgreSQL
    participant Redis as Redis

    C->>API: POST /api/v1/auth/login<br/>{email, password, orgId}
    API->>Auth: authenticate()
    Auth->>DB: findUser(email, orgId)
    DB-->>Auth: UserEntity
    Auth->>Hash: verifyPassword()
    Hash-->>Auth: valid

    alt 2FA Enabled
        Auth->>Redis: storeOTP(email, code)
        Auth->>C: {twoFaRequired: true}
    else 2FA Disabled
        Auth->>JWT: generateToken(user)
        JWT-->>Auth: JWT Token
        Auth->>Hash: hashRefreshToken()
        Auth->>Redis: storeRefreshToken()
        Auth->>C: Set Cookies<br/>{jwt, refresh_token}
        Auth-->>C: {status: true}
    end

sequenceDiagram
    participant C as Client
    participant API as Spring Boot API
    participant Magic as MagicUrlService
    participant Hash as HashingService
    participant Email as EmailService
    participant Redis as Redis
    participant RMQ as RabbitMQ
    participant JWT as JwtService

    Note over C,RMQ: Phase 1: Request Magic URL
    C->>API: POST /api/v1/magic-url<br/>{email, orgId}
    API->>Magic: sendMagicUrl()
    Magic->>Hash: generateSecureToken()
    Hash-->>Magic: token
    Magic->>Hash: hashToken(token)
    Hash-->>Magic: hashedToken
    Magic->>Redis: store(hashedToken, 10min)
    Magic->>Email: generateMagicUrlEmail()
    Email->>RMQ: enqueue(email)
    Magic-->>C: {status: true, message: "sent"}

    Note over C,JWT: Phase 2: Verify Magic URL
    C->>C: User clicks link in email
    C->>API: GET /api/v1/verify-magic-url?token=xxx
    API->>Magic: verifyMagicUrl(token)
    Magic->>Hash: hashToken(token)
    Magic->>Redis: getAndDelete(hashedToken)
    Redis-->>Magic: userData
    Magic->>JWT: generateToken(user)
    JWT-->>Magic: JWT Token
    Magic->>API: tokens
    API->>C: Set Cookies & Redirect

sequenceDiagram
    participant C as Client
    participant API as Spring Boot API
    participant TFA as TwoFactorService
    participant OTP as OtpService
    participant Email as EmailService
    participant Redis as Redis
    participant JWT as JwtService

    Note over C,Redis: Phase 1: Login triggers OTP
    C->>API: POST /api/v1/auth/login<br/>(2FA enabled user)
    API->>OTP: generateOTP()
    OTP->>OTP: random(1000-9999)
    OTP->>Redis: store(email:otp, 2-5min)
    OTP->>Email: sendOtpEmail(email, code)
    API-->>C: {twoFaRequired: true}

    Note over C,JWT: Phase 2: Verify OTP
    C->>API: POST /api/v1/auth/2fa/otp<br/>{email, otp, orgId}
    API->>TFA: verifyOtp()
    TFA->>Redis: get(email:otp)
    Redis-->>TFA: storedOtp
    TFA->>TFA: compare(otp, storedOtp)
    TFA->>Redis: delete(email:otp)
    TFA->>JWT: generateToken(user)
    JWT-->>TFA: JWT Token
    TFA->>API: tokens
    API->>C: Set Cookies<br/>{jwt, refresh_token}

sequenceDiagram
    participant C as Client
    participant API as Spring Boot API
    participant RT as RefreshTokenService
    participant Hash as HashingService
    participant JWT as JwtService
    participant Redis as Redis
    participant DB as PostgreSQL

    C->>API: POST /api/v1/auth/refresh<br/>Cookie: refresh_token, refresh_token_id
    API->>RT: refreshToken()
    RT->>Hash: hashToken(refresh_token)
    Hash-->>RT: hashedToken
    RT->>Redis: get(refresh_token_id)
    Redis-->>RT: storedToken
    RT->>RT: compare(hashedToken, storedToken)

    alt Token Valid
        RT->>Redis: delete(old_token_id)
        RT->>DB: getUser(userId)
        RT->>JWT: generateNewToken(user)
        JWT-->>RT: new JWT
        RT->>Hash: hashNewRefreshToken()
        RT->>Redis: store(new_token, 30min)
        RT->>DB: save(new_refresh_token)
        RT->>API: new tokens
        API->>C: Set New Cookies<br/>{jwt, refresh_token}
    else Token Invalid/Expired
        RT-->>API: error
        API-->>C: 401 Unauthorized
    end

sequenceDiagram
    participant C as Client
    participant API as Spring Boot API
    participant FP as ForgotPasswordService
    participant Hash as HashingService
    participant Email as EmailService
    participant Redis as Redis
    participant DB as PostgreSQL

    Note over C,Redis: Phase 1: Request Reset
    C->>API: POST /api/v1/forgot-password<br/>{email}
    API->>FP: generateResetToken()
    FP->>Hash: generateSecureToken(64 bytes)
    Hash-->>FP: token
    FP->>Hash: encodeBase64(token)
    Hash-->>FP: resetToken
    FP->>Redis: store(email:resetToken, TTL)
    FP->>Email: sendResetEmail(email, token)
    FP-->>C: {resetToken, message}

    Note over C,DB: Phase 2: Reset Password
    C->>API: POST /api/v1/reset-password<br/>{token, newPassword}
    API->>FP: resetPassword()
    FP->>Redis: get(token)
    Redis-->>FP: email
    FP->>Hash: bcrypt(newPassword)
    FP->>DB: updatePassword(email, hashedPassword)
    FP->>Redis: delete(token)
    FP-->>C: {status: true}

erDiagram
    ORGANISATIONS ||--o{ USERS : "has"
    ORGANISATIONS ||--o{ VALID_REDIRECTS : "configures"
    USERS ||--o{ REFRESH_TOKENS : "owns"

    ORGANISATIONS {
        uuid id PK
        string name
        string organisation_id UK "org_xxxxx"
        string api_key_hash "HMAC-SHA256"
        timestamp created_at
        timestamp updated_at
    }

    USERS {
        uuid id PK
        string mail_id
        string password_hash "Bcrypt"
        uuid organisation_id FK
        boolean two_fa_enabled
        timestamp created_at
        timestamp updated_at
    }

    REFRESH_TOKENS {
        uuid id PK
        uuid user_id FK
        string token_hash "SHA256"
        string client_ip
        string user_agent
        timestamp created_at
        timestamp expires_at
    }

    VALID_REDIRECTS {
        uuid id PK
        uuid organisation_id FK
        string redirect_url
        timestamp created_at
    }

    REDIS_KEYS {
        string key PK
        string value
        int ttl "Time To Live"
    }

    REDIS_KEYS ||--o{ OTP_STORAGE : "stores"
    REDIS_KEYS ||--o{ MAGIC_URL_TOKENS : "stores"
    REDIS_KEYS ||--o{ PASSWORD_RESET_TOKENS : "stores"
    REDIS_KEYS ||--o{ REFRESH_TOKEN_CACHE : "caches"

    OTP_STORAGE {
        string key "email:otp"
        string otp "4-digit code"
        int ttl "2-5 minutes"
    }

    MAGIC_URL_TOKENS {
        string key "magic:hashedToken"
        json value "user data"
        int ttl "10 minutes"
    }

    PASSWORD_RESET_TOKENS {
        string key "reset:email"
        string token
        int ttl "configurable"
    }

    REFRESH_TOKEN_CACHE {
        string key "refresh:tokenId"
        string hashedToken
        int ttl "30 minutes"
    }

graph LR
    subgraph "Application Layer"
        Service[Auth/Magic/OTP Service]
        Template[EmailTemplateService]
        Producer[MailSenderService]
    end

    subgraph "Message Queue"
        Exchange[EMAIL_EXCHANGE]
        Queue[Email Queue]
    end

    subgraph "Delivery Layer"
        Consumer[Email Consumer]
        SMTP[SMTP Server]
    end

    subgraph "User"
        Inbox[User Inbox]
    end

    Service -->|Generate| Template
    Template -->|HTML Email| Producer
    Producer -->|Enqueue| Exchange
    Exchange -->|Route| Queue
    Queue -->|Consume| Consumer
    Consumer -->|Send| SMTP
    SMTP -->|Deliver| Inbox

    style Service fill:#4caf50
    style Template fill:#2196f3
    style Exchange fill:#ff9800
    style Queue fill:#ff9800
    style Consumer fill:#9c27b0
    style SMTP fill:#607d8b
    style Inbox fill:#f44336

graph TB
    subgraph "Token Generation"
        Gen[Generate Token]
        Sign[RS256 Signature]
        Store[Store in Redis]
    end

    subgraph "Token Storage"
        Cookie[HttpOnly Cookie]
        Redis[(Redis Cache)]
        DB[(PostgreSQL)]
    end

    subgraph "Token Validation"
        Extract[Extract from Cookie]
        Verify[Verify Signature]
        Check[Check Expiration]
        Lookup[Lookup in Redis]
    end

    subgraph "Security Measures"
        Rotate[Token Rotation]
        Revoke[Revocation Support]
        Expire[Auto Expiration]
    end

    Gen --> Sign
    Sign --> Store
    Store --> Cookie
    Store --> Redis
    Store --> DB

    Extract --> Verify
    Verify --> Check
    Check --> Lookup

    Lookup --> Rotate
    Lookup --> Revoke
    Lookup --> Expire

    style Sign fill:#f44336
    style Cookie fill:#4caf50
    style Redis fill:#ff9800
    style Verify fill:#2196f3
    style Rotate fill:#9c27b0