# supabase/auth architecture

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

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

## Overview

##### Main Components

a. Core Service Components:
- API Server (Main Auth Service)
- Database Layer (PostgreSQL)
- External Provider Integration Layer
- Email/SMS Service Layer
- JWT Management System
- Admin Interface

b. External Components:
- OAuth Providers (GitHub, Google, etc.)
- SMTP Services
- SMS Providers
- CAPTCHA Services

##### Key Architectural Elements

a. API Layer Structure:
- Public Endpoints (/signup, /token, /verify, etc.)
- Protected Endpoints (/user, /logout)
- Admin Endpoints (/admin/*)
- OAuth Endpoints (/authorize, /callback)

b. Internal Services:
- Authentication Flow Manager
- Token Manager (JWT)
- User Manager
- Mail/SMS Manager
- Rate Limiter
- Audit Logger

**Client Layer**

**API Gateway Layer**

**Core Service Layer**

**Integration Layer**

**Storage Layer**

##### Key Flows to Highlight

a. Authentication Flows:
- Email/Password Sign-in
- OAuth Sign-in
- Magic Link
- Phone Authentication
- Token Refresh

b. User Management Flows:
- User Registration
- Password Recovery
- Email Verification
- Account Updates

##### Important Relationships

- JWT token flow between components
- Database interactions
- External service communications
- Security boundary demarcations

##### Technical Details

a. Infrastructure Components:
- Rate Limiting
- CAPTCHA Protection
- Audit Logging
- Observability (Metrics/Tracing)

b. Security Features:
- Password Hashing
- Token Management
- Rate Limiting
- Reauthentication

##### Implementation Notes

- Clear separation between public and admin APIs
- Security boundaries
- Stateless nature of the JWT implementation
- Database schema relationships
- External service integration points

##### Specific Architectural Patterns

- Command Pattern (cmd/ directory structure)
- Repository Pattern (models/ directory)
- Middleware Pattern (api/middleware.go)
- Provider Pattern (api/provider/ directory)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph Clients
        WebClient["Web Client"]
        MobileClient["Mobile Client"]
        AdminClient["Admin Client"]:::admin
    end

    %% API Gateway Layer
    subgraph "API Gateway"
        PublicAPI["Public API Endpoints"]:::api
        AdminAPI["Admin API"]:::admin
        OAuthAPI["OAuth Endpoints"]:::api
    end

    %% Core Service Layer
    subgraph "Core Services"
        AuthService["Auth Service"]:::core
        UserMgmt["User Management"]:::core
        TokenMgmt["Token Management"]:::core
        AuthFlow["Auth Flow Manager"]:::core
        PassMgmt["Password Management"]:::core
        RateLimiter["Rate Limiter"]:::security
        AuditLog["Audit Logger"]:::security
        JWTMgmt["JWT Management"]:::security
    end

    %% Integration Layer
    subgraph "External Services"
        EmailService["Email Service"]:::comms
        SMSService["SMS Service"]:::comms
        OAuthProviders["OAuth Providers"]:::oauth
        CAPTCHAService["CAPTCHA Service"]:::security
    end

    %% Storage Layer
    subgraph "Storage Layer"
        DB[(Database)]:::storage
        Migrations["DB Migrations"]:::storage
    end

    %% Relationships
    WebClient --> PublicAPI
    MobileClient --> PublicAPI
    AdminClient --> AdminAPI
    
    PublicAPI --> AuthService
    PublicAPI --> AuthFlow
    AdminAPI --> UserMgmt
    OAuthAPI --> OAuthProviders
    
    AuthService --> UserMgmt
    AuthService --> TokenMgmt
    AuthService --> JWTMgmt
    AuthFlow --> PassMgmt
    AuthFlow --> EmailService
    AuthFlow --> SMSService
    
    UserMgmt --> DB
    TokenMgmt --> DB
    PassMgmt --> DB
    
    RateLimiter --> PublicAPI
    AuditLog --> DB
    
    Migrations --> DB

    %% Click Events
    click AuthService "https://github.com/supabase/auth/blob/master/internal/api/api.go"
    click DB "https://github.com/supabase/auth/tree/master/internal/storage/"
    click OAuthProviders "https://github.com/supabase/auth/tree/master/internal/api/provider/"
    click EmailService "https://github.com/supabase/auth/tree/master/internal/mailer/"
    click SMSService "https://github.com/supabase/auth/tree/master/internal/api/sms_provider/"
    click JWTMgmt "https://github.com/supabase/auth/blob/master/internal/conf/jwk.go"
    click AdminClient "https://github.com/supabase/auth/tree/master/client/admin/"
    click UserMgmt "https://github.com/supabase/auth/blob/master/internal/models/user.go"
    click RateLimiter "https://github.com/supabase/auth/blob/master/internal/api/ratelimits.go"
    click AuditLog "https://github.com/supabase/auth/blob/master/internal/api/audit.go"
    click AuthFlow "https://github.com/supabase/auth/blob/master/internal/api/auth.go"
    click TokenMgmt "https://github.com/supabase/auth/blob/master/internal/api/token.go"
    click PassMgmt "https://github.com/supabase/auth/blob/master/internal/api/password.go"
    click OAuthAPI "https://github.com/supabase/auth/blob/master/internal/api/external_oauth.go"
    click Migrations "https://github.com/supabase/auth/tree/master/migrations/"

    %% Styles
    classDef core fill:#2374ab
    classDef api fill:#48cae4
    classDef admin fill:#023047
    classDef security fill:#d62828
    classDef comms fill:#ff9e00
    classDef oauth fill:#38b000
    classDef storage fill:#7209b7

    %% Legend
    subgraph Legend
        CoreService["Core Services"]:::core
        APIEndpoint["API Endpoints"]:::api
        AdminComp["Admin Components"]:::admin
        SecurityComp["Security Components"]:::security
        CommsService["Communication Services"]:::comms
        OAuthComp["OAuth Components"]:::oauth
        StorageComp["Storage Components"]:::storage
    end
```
