# pilcrowonpaper/arctic architecture

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

- Interactive diagram: https://gitdiagram.com/pilcrowonpaper/arctic
- Repository: https://github.com/pilcrowonpaper/arctic

## Overview

##### Main Components

a. Core Components:
- OAuth2 Client Base Layer
- Provider-Specific Implementations
- OIDC (OpenID Connect) Layer
- Utility Services
- Error Handling System

b. External Integration Points:
- OAuth2 Providers (50+ supported services)
- Application Integration Layer

**┌─ Application Layer (Consumer Applications) ─────────────────────┐**

- Arctic Public API ──────────────────────────────────────────┐ │

- ┌─ Provider-Specific Implementations ─┐                     │ │
- (GitHub, Google, Discord, etc.)    │                     │ │
- ┬─────────────────┘                     │ │

- ┌─ Core OAuth2 ────┴─────┐    ┌─ OpenID Connect (OIDC) ─┐  │ │
- Authorization        │    │ - ID Token Handling      │  │ │
- Token Management     │◄───┤ - JWT Validation        │  │ │
- PKCE Support        │    └────────────────────────┘  │ │
- ┬──────────┘                               │ │

- ┌─ Utilities ┴──────────┐    ┌─ Error Handling ───────┐│ │
- State Generation    │    │ - OAuth2RequestError    ││ │
- Code Verification   │    │ - ArcticFetchError     ││ │
- ┬──────────┘    └────────────────────────┘│ │

- ┼──────────────────────────────────────────┘ │

**┌───────────────┴─────────────────────────────────────────┐  │**
- External OAuth2 Providers                                │  │
- (50+ Services including GitHub, Google, Discord, etc.)   │  │
- ┘  │

- ┘

##### Key Interactions to Highlight

a. Authorization Flow:
- Application → Arctic Client → OAuth2 Provider
- OAuth2 Provider → Arctic Client → Application
- Token validation and refresh paths

b. Error Handling Flow:
- Error propagation from providers
- Library-specific error handling

##### Important Details

- Supported OAuth2 flows (Authorization Code Flow)
- PKCE support
- Token management capabilities
- Provider-specific customizations
- Error handling mechanisms

##### Technical Specifications

- That it's built on Fetch API
- Runtime-agnostic nature
- TypeScript integration points

##### Notes for Implementation

- Clear boundaries between the library and external systems
- Modular nature of provider implementations
- Security features (PKCE, state validation)

Remember to include version compatibility notes and any provider-specific considerations in supplementary documentation.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph AppLayer["Application Layer"]
        App[Consumer Applications]
    end

    subgraph ArcticAPI["Arctic Public API"]
        subgraph Providers["Provider-Specific Implementations"]
            ProviderImpl["OAuth2 Provider Implementations"]:::provider
        end

        subgraph CoreOAuth["Core OAuth2"]
            Auth["Authorization Management"]:::core
            TokenMgmt["Token Management"]:::core
            PKCE["PKCE Support"]:::core
        end

        subgraph OIDC["OpenID Connect (OIDC)"]
            IDToken["ID Token Handling"]:::oidc
            JWTValid["JWT Validation"]:::oidc
        end

        subgraph Utils["Utilities"]
            StateGen["State Generation"]:::util
            CodeVerif["Code Verification"]:::util
            Request["Request Handling"]:::util
        end

        subgraph ErrorHandling["Error Handling"]
            OAuth2Err["OAuth2RequestError"]:::error
            ArcticErr["ArcticFetchError"]:::error
            UnexpectedErr["UnexpectedErrorResponse"]:::error
        end
    end

    subgraph External["External OAuth2 Providers"]
        Providers["GitHub, Google, Discord, etc."]:::external
    end

    %% Connections
    App --> ProviderImpl
    ProviderImpl --> CoreOAuth
    CoreOAuth --> OIDC
    CoreOAuth --> Utils
    CoreOAuth --> ErrorHandling
    CoreOAuth --> External
    OIDC --> Utils
    OIDC --> ErrorHandling

    %% Click Events
    click ProviderImpl "https://github.com/pilcrowonpaper/arctic/tree/main/src/providers/"
    click Auth "https://github.com/pilcrowonpaper/arctic/blob/main/docs/pages/reference/main/OAuth2Client/createAuthorizationURL.md"
    click TokenMgmt "https://github.com/pilcrowonpaper/arctic/tree/main/docs/pages/reference/main/OAuth2Tokens/"
    click IDToken "https://github.com/pilcrowonpaper/arctic/blob/main/src/oidc.ts"
    click StateGen "https://github.com/pilcrowonpaper/arctic/blob/main/docs/pages/reference/main/generateState.md"
    click CodeVerif "https://github.com/pilcrowonpaper/arctic/blob/main/docs/pages/reference/main/generateCodeVerifier.md"
    click Request "https://github.com/pilcrowonpaper/arctic/blob/main/src/request.ts"
    click OAuth2Err "https://github.com/pilcrowonpaper/arctic/blob/main/docs/pages/reference/main/OAuth2RequestError.md"
    click ArcticErr "https://github.com/pilcrowonpaper/arctic/blob/main/docs/pages/reference/main/ArcticFetchError.md"
    click UnexpectedErr "https://github.com/pilcrowonpaper/arctic/blob/main/docs/pages/reference/main/UnexpectedErrorResponseBodyError.md"

    %% Styling
    classDef core fill:#2374ab
    classDef provider fill:#57a773
    classDef util fill:#ffa62b
    classDef error fill:#ff686b
    classDef oidc fill:#9381ff
    classDef external fill:#808080

    %% Legend
    subgraph Legend
        CoreLegend["Core Components"]:::core
        ProviderLegend["Provider Components"]:::provider
        UtilLegend["Utility Services"]:::util
        ErrorLegend["Error Handling"]:::error
        OIDCLegend["OIDC Components"]:::oidc
        ExtLegend["External Systems"]:::external
    end
```
