# toolbeam/openauth architecture

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

- Interactive diagram: https://gitdiagram.com/toolbeam/openauth
- Repository: https://github.com/toolbeam/openauth

## Overview

##### Project Type and Purpose

**OpenAuth** is a **centralized authentication server** designed for self-hosting. It provides a standards-based OAuth 2.0 compliant authentication solution suitable for web applications, mobile apps, single-page applications (SPAs), APIs, and third-party clients. OpenAuth aims to offer a universal, customizable, and self-hosted alternative to SaaS authentication services like Auth0 or Clerk, allowing organizations to maintain full control over their authentication infrastructure.

##### File Structure Analysis

The provided file tree reveals a **monorepo** structure with multiple packages and examples, indicating a modular and extensible architecture. Key observations include:

- **Top-Level Directories:**
- `.github`: Contains workflow configurations for CI/CD processes such as testing, formatting, releasing, and documentation.
- `examples`: Demonstrates various deployment scenarios and client integrations using frameworks like Astro, Next.js, React, and SvelteKit.
- `packages`: Houses the core OpenAuth package (`openauth`) and its associated scripts, providers, storage solutions, UI components, and utilities.
- `www`: Manages the documentation website, built with Astro, including content, components, and styles.
- `scripts`: Contains utility scripts for tasks like code formatting.

- **Configuration Files:**
- `bunfig.toml` and `bun.lockb`: Indicate the use of Bun as a JavaScript runtime.
- `.prettierrc`: Configures code formatting rules.
- `tsconfig.json`: TypeScript configuration for various parts of the project.
- `package.json`: Manages dependencies and scripts for each package.

- **Patterns and Architectural Choices:**
- **Modular Architecture:** Separation of concerns through distinct packages and examples.
- **Provider-Based Extensions:** The `src/provider` directory within the `openauth` package suggests a plugin-like system for integrating multiple authentication providers.
- **Storage Abstractions:** The `src/storage` directory indicates a strategy pattern for supporting various storage backends (e.g., AWS DynamoDB, Cloudflare KV, in-memory storage).
- **UI Components:** The presence of reusable UI components in `src/ui` facilitates customizable and themeable interfaces.

##### README Insights

The README provides comprehensive information about OpenAuth's capabilities, deployment options, and customization features:

- **Deployment Flexibility:** Supports deployment on Node.js, Bun, AWS Lambda, Cloudflare Workers, or as a standalone service.
- **Standards Compliance:** Implements OAuth 2.0 specifications, ensuring compatibility with any OAuth client.
- **Customizability:** Offers prebuilt, themeable UI components that can be customized or replaced as needed.
- **Extensibility:** Allows the addition of various authentication providers and storage solutions.
- **Integration with SST:** Built by the maintainers of SST, suggesting seamless infrastructure management and deployment capabilities.

To accurately represent OpenAuth's architecture, follow these guidelines:

##### Auth Server Core
- **Framework:** Built on [Hono](https://github.com/honojs/hono), a minimalist web framework.
- **Issuer Function:** Central function that initializes the Hono app with configured providers, storage, subjects, and callbacks.

##### Authentication Providers
- **Third-Party Providers:** Google, GitHub, Discord, Facebook, etc.
- **Built-In Providers:** Email/Password, Pin Code.
- **Custom Providers:** Ability to implement additional or proprietary providers.

##### Storage Layer
- **Memory Storage:** For testing purposes.
- **Persistent Storage:** AWS DynamoDB, Cloudflare KV, etc.

##### UI Components
- **Prebuilt UI:** Themeable interfaces for authentication flows.
- **Custom UI:** Ability to replace or extend default UI components.

##### Deployment Targets
- **Node.js/Bun Servers**
- **AWS Lambda Functions**
- **Cloudflare Workers**

##### Client Applications (Examples)
- **Frameworks:** Astro, Next.js, React, SvelteKit.
- **Purpose:** Demonstrate integration with OpenAuth.

##### Documentation Site
- **Built with Astro:** Located in the `www` directory.
- **Content:** Guides, API documentation, examples.

##### CI/CD Workflows
- **GitHub Actions:** Automated workflows for testing, formatting, releasing, and deploying documentation.

##### b. Relationships and Interactions

- **Auth Server ↔ Providers:**
- The Auth Server communicates with various authentication providers to handle user authentication flows.

- **Auth Server ↔ Storage Layer:**
- Stores and retrieves data such as refresh tokens, password hashes, and minimal user information.

- **Client Applications ↔ Auth Server:**
- Utilize OAuth 2.0 flows (Authorization Code with or without PKCE) to authenticate users and obtain access/refresh tokens.

- **Deployment Targets ↔ Auth Server:**
- The Auth Server is deployed on chosen infrastructure (e.g., AWS Lambda, Cloudflare Workers) based on scalability and performance requirements.

- **Documentation Site ↔ Packages/Examples:**
- Provides guidance and references to various packages and examples for integration.

##### c. Architectural Patterns and Design Principles

- **Modular Design:** Facilitates extensibility and maintainability by separating concerns into distinct packages and components.

- **Plugin Architecture for Providers:** Allows easy addition or removal of authentication providers without altering the core system.

- **Stateless Server:** Emphasizes statelessness for scalability, with minimal state stored in the storage layer.

- **Separation of Concerns:** Distinct divisions between core authentication logic, UI components, storage, and client integrations.

##### d. Relevant Technologies and Frameworks

- **Hono:** Web framework for building the Auth Server.
- **Bun:** JavaScript runtime used for development and performance optimization.
- **TypeScript:** Ensures type safety across the codebase.
- **Valibot:** Schema validation library used for defining subjects.
- **SST:** Infrastructure management tool for deploying OpenAuth components.
- **Astro, Next.js, React, SvelteKit:** Frameworks used in client application examples.
- **GitHub Actions:** Automates CI/CD workflows.
- **OAuth 2.0:** Authentication protocol implemented by OpenAuth.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Subgraphs and modules
    subgraph "Core Services"
        AuthServer("Auth Server Core"):::core
        UIComponents("UI Components"):::frontend
    end
    subgraph "External Services"
        Providers("Authentication Providers"):::external
    end
    subgraph "Storage Layer"
        Storage("Storage Layer"):::storage
    end
    subgraph "Client Applications"
        Clients("Client Applications"):::client
    end
    subgraph "Infrastructure"
        Deployment("Deployment Targets"):::infrastructure
        CICD("CI/CD Workflows"):::infrastructure
    end
    subgraph "Documentation"
        Docs("Documentation Site"):::documentation
    end

    %% Connections
    Clients -->|"OAuth 2.0"| AuthServer
    AuthServer -->|"Uses"| Providers
    AuthServer -->|"Uses"| Storage
    AuthServer -->|"Uses"| UIComponents
    AuthServer -->|"Deployed on"| Deployment
    Docs -->|"References"| Providers
    Docs -->|"References"| Storage
    Docs -->|"References"| Clients
    CICD -->|"Automates"| AuthServer
    CICD -->|"Automates"| Docs

    %% Click Events
    click AuthServer "https://github.com/toolbeam/openauth/blob/master/packages/openauth/src/index.ts"
    click Providers "https://github.com/toolbeam/openauth/tree/master/packages/openauth/src/provider"
    click Storage "https://github.com/toolbeam/openauth/tree/master/packages/openauth/src/storage"
    click UIComponents "https://github.com/toolbeam/openauth/tree/master/packages/openauth/src/ui"
    click Deployment "https://github.com/toolbeam/openauth/tree/master/examples/issuer"
    click Clients "https://github.com/toolbeam/openauth/tree/master/examples/client"
    click Docs "https://github.com/toolbeam/openauth/tree/master/www"
    click CICD "https://github.com/toolbeam/openauth/tree/master/.github/workflows"

    %% Styles
    classDef core fill:#1f77b4,stroke:#333,stroke-width:1px
    classDef external fill:#2ca02c,stroke:#333,stroke-width:1px
    classDef storage fill:#ff7f0e,stroke:#333,stroke-width:1px
    classDef frontend fill:#9467bd,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#7f7f7f,stroke:#333,stroke-width:1px
    classDef client fill:#d62728,stroke:#333,stroke-width:1px
    classDef documentation fill:#17becf,stroke:#333,stroke-width:1px
```
