# sidebase/nuxt-auth architecture

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

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

## Overview

##### Main Components
- Nuxt Auth Module Core – Represent the core module file (src/module.ts) which acts as the entry point when the module is injected into a Nuxt app via nuxt.config.ts.
- Runtime Logic:
- Client-side functionalities under src/runtime (e.g., composables for authentication, such as useAuth and useAuthState, utilities for routing/navigations, and middleware – like sidebase-auth).
- Server-side components (found in src/runtime/server) including server plugins, services (e.g., authjs service and error handling), and API endpoints (both in the main module and in playground examples).
- Provider Implementations – Clearly differentiate between the “authjs” provider and the “local” provider. Note that separate playground directories (playground-authjs and playground-local) illustrate these implementations.
- Documentation – Highlight the docs folder (with its vitepress structure), which acts as a user guide for setup, configuration, and upgrades. This documentation ties into how the module is used in real-world scenarios.
- Testing/CI & Development Tools – Although secondary to runtime functionality, include elements like GitHub workflows, linting, and testing configurations (Vitest, Playwright, etc.) which illustrate the project’s continuous integration and quality assurance pipelines.

##### Relationships and Interactions
- A two-pronged runtime split:
- Client Side: Illustrate how composables (useAuth, useAuthState) interact with application-side session management and middleware (e.g., sidebase-auth) to protect pages.
- Server Side: Display how the server plugins and services (assert origin checks, token retrieval, error handlers) interconnect to provide secure API endpoints.
- “Playground Applications” to signify testing environments:
- One playground simulates a non-static Nuxt 3 app with provider “authjs”.
- The other simulates a static page with an external authentication backend (“local”), using separate front-end and back-end instances.
- Optionally, denote the integration with external OAuth providers (like GitHub, Google, etc.) as part of the authentication flow.

##### Architectural Patterns and Design Principles
- Separation of concerns: distinct modules for client- and server-side logic, isolation of provider-specific behaviors, and a clear division between the core module code and support infrastructure (such as testing and CI).
- Usage of composable functions and middleware that adhere to the modern reactive programming practices found in Nuxt 3.
- Mention the extensible and pluggable nature of the module which allows users to customize refresh behaviors and session handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Integration
    NuxtConfig["Nuxt Config (nuxt.config.ts)"]:::external
    Core["Nuxt Auth Module Core"]:::core
    NuxtConfig -->|"injects"| Core

    %% Client Runtime Layer
    subgraph "Client Runtime"
        ClientAuthjs["Authjs Composables"]:::client
        ClientLocal["Local Composables"]:::client
        Middleware["Middleware (sidebase-auth)"]:::middleware
    end
    Core -->|"initializes"| ClientAuthjs
    Core -->|"initializes"| ClientLocal
    Core -->|"registers"| Middleware

    %% Server Runtime Layer
    subgraph "Server Runtime"
        ServerAuthjs["Authjs Service"]:::server
        ServerGeneral["General Server Components"]:::server
    end
    Core -->|"exposes"| ServerAuthjs
    Core -->|"exposes"| ServerGeneral

    ClientAuthjs -->|"calls_API"| ServerAuthjs
    ClientLocal -->|"calls_API"| ServerGeneral
    Middleware -->|"secures_routes"| ServerGeneral

    %% Provider Implementations
    subgraph "Provider Implementations"
        PlaygroundAuthjs["Playground: Authjs"]:::provider
        PlaygroundLocal["Playground: Local"]:::provider
    end
    Core -->|"supports"| PlaygroundAuthjs
    Core -->|"supports"| PlaygroundLocal

    %% Documentation & CI/Dev Tools
    subgraph "Documentation & CI/Dev Tools"
        Docs["Documentation Site"]:::docs
        CI["Testing/CI & Dev Tools"]:::ci
    end
    Core -->|"documented_in"| Docs
    Docs -->|"guides_usage"| CI

    %% Additional Note for External OAuth Providers
    OAuthNote["Note:_External_OAuth_Providers_integrated"]:::note
    ServerAuthjs -->|"handles"| OAuthNote

    %% Click Events Mapping
    click Core "https://github.com/sidebase/nuxt-auth/blob/main/src/module.ts"
    click ClientAuthjs "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/composables/authjs/useAuth.ts"
    click ClientAuthjs "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/composables/authjs/useAuthState.ts"
    click ClientLocal "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/composables/local/useAuth.ts"
    click ClientLocal "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/composables/local/useAuthState.ts"
    click Middleware "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/middleware/sidebase-auth.ts"
    click ServerAuthjs "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/server/services/authjs/nuxtAuthHandler.ts"
    click ServerAuthjs "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/server/services/authjs/utils.ts"
    click ServerGeneral "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/server/plugins/assertOrigin.ts"
    click ServerGeneral "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/server/services/errors.ts"
    click ServerGeneral "https://github.com/sidebase/nuxt-auth/blob/main/src/runtime/server/services/index.ts"
    click PlaygroundAuthjs "https://github.com/sidebase/nuxt-auth/tree/main/playground-authjs"
    click PlaygroundLocal "https://github.com/sidebase/nuxt-auth/tree/main/playground-local"
    click Docs "https://github.com/sidebase/nuxt-auth/blob/main/docs/.vitepress"
    click CI "https://github.com/sidebase/nuxt-auth/tree/main/.github/workflows"
    click CI "https://github.com/sidebase/nuxt-auth/blob/main/vitest.config.ts"
    click CI "https://github.com/sidebase/nuxt-auth/blob/main/playground-local/vitest.config.ts"
    click CI "https://github.com/sidebase/nuxt-auth/tree/main/playground-local/tests"

    %% Styles
    classDef external fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef core fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef client fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef middleware fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef server fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef provider fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef docs fill:#ffe4b5,stroke:#000,stroke-width:2px;
    classDef ci fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef note fill:#fffacd,stroke:#000,stroke-width:2px;
```
