# ibrahimalbarghouthi/gotrue architecture

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

- Interactive diagram: https://gitdiagram.com/ibrahimalbarghouthi/gotrue
- Repository: https://github.com/ibrahimalbarghouthi/gotrue

## Overview

##### Main Components

a) Core API Service Layer
- Authentication Controllers (auth.go, token.go)
- User Management (user.go, signup.go)
- External Provider Integration (external.go, provider/*.go)
- Admin Functions (admin.go)
- Audit System (audit.go)

b) Database Layer
- SQL Database (supported by storage/sql.go)
- Migration System (migrations/*.sql)
- Models (models/*.go)

c) External Services Integration
- OAuth Providers (GitHub, GitLab, Bitbucket, Google, Facebook)
- SMTP Email Service
- SAML Integration
- Webhook System

d) Supporting Systems
- Configuration Management (conf/*.go)
- Mailer System (mailer/*.go)
- Crypto Functions (crypto/crypto.go)
- Tracing System (Datadog integration)

**[Client Applications]**
- ↓
**[API Endpoints Layer]**
- ↓
**[Authentication & Authorization Layer]**
- ↓
**[Core Services Layer]**
- ↓
**[Data Access Layer]**
- ↓
**[External Services]**

##### Key Relationships to Highlight

- Flow of authentication requests through the system
- Interaction between the API layer and external OAuth providers
- Demonstrate email notification flows
- Database interactions for user management
- Webhook notification paths

##### Specific Implementation Details

a) API Layer (Blue)
**[REST API Endpoints]**
- /signup
- /verify
- /token
- /user
- /logout
- /recover

**[Client] → [API Gateway] → [Auth Handler] → [Token Service]**
- ↓
- [External Providers]

c) Data Flow (Orange)
**[Models] → [Storage Layer] → [Database]**

##### Additional Elements

- Configuration components showing environment variable integration
- Security boundaries and JWT token flow
- Audit logging paths
- Email template system integration

##### Critical Interactions

- User registration flow
- Password recovery process
- External provider authentication
- Token refresh mechanism
- Webhook notification system

##### Notes for Implementation

- Keep the main flow clear and centered
- Related components together
- Scalable components
- Security boundaries clearly
- Configuration dependencies

##### Technical Details to Highlight

- JWT token handling
- Database migrations
- External provider integration
- Email template system
- Audit logging
- Tracing integration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        Client["Client Applications"]
    end

    subgraph "API Endpoints Layer"
        API["REST API Gateway"]:::api
        click API "https://github.com/ibrahimalbarghouthi/gotrue/tree/master/api"
        
        Auth["Authentication Controllers"]:::controller
        click Auth "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/auth.go"
        
        Token["Token Service"]:::controller
        click Token "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/token.go"
        
        User["User Management"]:::controller
        click User "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/user.go"
        
        Admin["Admin Service"]:::controller
        click Admin "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/admin.go"
    end

    subgraph "Core Services Layer"
        Audit["Audit System"]:::service
        click Audit "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/audit.go"
        
        Hooks["Webhook System"]:::service
        click Hooks "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/hooks.go"
        
        Mailer["Mailer System"]:::service
        click Mailer "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/mailer/mailer.go"
        
        Config["Configuration"]:::service
        click Config "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/conf/configuration.go"
        
        Crypto["Crypto Service"]:::service
        click Crypto "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/crypto/crypto.go"
        
        Trace["Tracing System"]:::service
        click Trace "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/tracer.go"
    end

    subgraph "External Providers Layer"
        Github["GitHub"]:::provider
        click Github "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/provider/github.go"
        
        Gitlab["GitLab"]:::provider
        click Gitlab "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/provider/gitlab.go"
        
        Google["Google"]:::provider
        click Google "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/provider/google.go"
        
        Facebook["Facebook"]:::provider
        click Facebook "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/provider/facebook.go"
        
        SAML["SAML"]:::provider
        click SAML "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/api/provider/saml.go"
    end

    subgraph "Data Layer"
        Storage["Storage Layer"]:::storage
        click Storage "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/storage/sql.go"
        
        Models["Data Models"]:::storage
        click Models "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/models/user.go"
        
        DB[(SQL Database)]:::db
        click DB "https://github.com/ibrahimalbarghouthi/gotrue/blob/master/migrations/schema.sql"
        
        Migration["Migration System"]:::storage
        click Migration "https://github.com/ibrahimalbarghouthi/gotrue/tree/master/migrations"
    end

    subgraph "External Services"
        SMTP["SMTP Service"]:::external
    end

    %% Connections
    Client --> API
    API --> Auth
    API --> Token
    API --> User
    API --> Admin

    Auth --> Crypto
    Auth --> Mailer
    Auth --> Storage
    Auth --> Audit
    Auth --> Hooks

    User --> Storage
    User --> Mailer
    User --> Audit

    Token --> Storage
    Token --> Crypto

    Storage --> DB
    Storage --> Models
    DB --> Migration

    Auth --> Github
    Auth --> Gitlab
    Auth --> Google
    Auth --> Facebook
    Auth --> SAML

    Mailer --> SMTP

    %% Styling
    classDef api fill:#2196F3,stroke:#1565C0,color:white
    classDef controller fill:#42A5F5,stroke:#1565C0,color:white
    classDef service fill:#64B5F6,stroke:#1565C0,color:white
    classDef provider fill:#81C784,stroke:#388E3C,color:white
    classDef storage fill:#FFA726,stroke:#F57C00,color:white
    classDef db fill:#FF7043,stroke:#E64A19,color:white
    classDef external fill:#9575CD,stroke:#5E35B1,color:white

    %% Legend
    subgraph Legend
        L1["API Service"]:::api
        L2["Controllers"]:::controller
        L3["Core Services"]:::service
        L4["External Providers"]:::provider
        L5["Storage Components"]:::storage
        L6["Database"]:::db
        L7["External Services"]:::external
    end
```
