# asgardeo/javascript architecture

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

- Interactive diagram: https://gitdiagram.com/asgardeo/javascript
- Repository: https://github.com/asgardeo/javascript

## Overview

##### Project type and purpose
- This is a large monorepo hosting Asgardeo’s JavaScript SDKs: framework-agnostic core libraries, browser and Node/Express SDKs, and framework bindings for React, Next.js, Nuxt, Vue and routing libraries (React Router, Tanstack Router).
- Its purpose is to let front-end and back-end applications integrate with the Asgardeo identity service via OIDC/OAuth2 flows, theming, i18n and session management.

##### File‐structure / architectural patterns
- Top level
- docs/ – static documentation and images for gh-pages
- packages/ – one folder per SDK package
- .github/workflows – CI and publish pipelines
- nx.json, pnpm-workspace.yaml – monorepo workspace config
- packages/ contains:
- __legacy__ subfolders for previous major versions
- src/ with framework-specific entry-points, API wrappers, context providers, hooks, middleware, models and utils
- tests and tsconfig/build configs per package
- Shared sub-modules
- core (authentication client, branding, i18n)
- javascript (core SDK with API, constants, errors, models, utils)
- i18n (translation bundles)
- Framework-specific packages depend on core/javascript/i18n:
- @asgardeo/browser, @asgardeo/node, @asgardeo/express
- @asgardeo/react, @asgardeo/nextjs, @asgardeo/nuxt, @asgardeo/vue
- @asgardeo/react-router, @asgardeo/tanstack-router

##### Key README insights
- Lists each published package and its intended environment.
- Points to QuickStarts for React and Next.js, implying client apps use those SDKs.
- Emphasizes modularity, extensibility and common contribution workflows.

a. Main Components
- Monorepo root (workspace tooling, CI/CD, docs site)
- Shared libraries: Core, JavaScript SDK, i18n
- Environment SDKs: Browser, Node, Express
- Framework bindings: React, Next.js, Nuxt, Vue, React-Router, Tanstack Router
- External Asgardeo Identity Service (OIDC/OAuth2)
- Consumer applications (sample React, Next.js, Vue, Node/Express servers)
b. Interactions
- CI/CD (GitHub Actions) triggers lint, test, build, changelog aggregation, publish to npm, docs deploy to gh-pages
- Each package imports common core modules; framework bindings import JavaScript SDK + core + i18n
- Apps depend on framework SDK packages to call Asgardeo endpoints for sign-in, token exchange, session management
- SDKs call out to Asgardeo’s REST/OIDC endpoints and return tokens → apps use tokens to call protected APIs
c. Architectural patterns
- Monorepo with workspace tool (pnpm + Nx) for cross-package versioning and build orchestration
- Layered library design: core → language SDK → environment SDK → framework SDK → application
- Legacy folder pattern indicates migration path/versioning
- CI pipelines implementing changeset-based release (changeset config, workflows)
d. Key technologies
- TypeScript for all source
- Rollup / esbuild for bundling
- Vitest / Jest for testing
- GitHub Actions for CI/CD and npm publishing
- pnpm + nx for workspace management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Root
    subgraph "Monorepo Root"
        direction TB
        pnpm["pnpm-workspace.yaml"]:::root
        nx["nx.json"]:::root
        workflows[".github/workflows"]:::ci
        docs["docs/"]:::docs
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        core["Core"]:::core
        js["JavaScript SDK"]:::core
        i18n["i18n"]:::core
    end

    %% Environment SDKs
    subgraph "Environment SDKs"
        direction TB
        browser["Browser SDK"]:::env
        node["Node SDK"]:::env
        express["Express SDK"]:::env
    end

    %% Framework Bindings
    subgraph "Framework Bindings"
        direction TB
        react["React"]:::framework
        nextjs["Next.js"]:::framework
        nuxt["Nuxt"]:::framework
        vue["Vue"]:::framework
        rr["React Router"]:::framework
        tr["Tanstack Router"]:::framework
    end

    %% Consumer Applications
    subgraph "Consumer Applications"
        direction TB
        samples["Sample Apps"]:::apps
    end

    %% External Service
    Asgardeo["Asgardeo Identity Service"]:::external

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        commit["Commit Code"]:::ci
        lint["Lint & Test"]:::ci
        build["Build & Bundle"]:::ci
        publish["Publish to npm"]:::ci
        commit --> workflows
        workflows --> lint
        lint --> build
        build --> publish
        publish --> docs
    end

    %% Dependencies
    pnpm --> core
    nx --> core
    core --> js
    js --> i18n

    js --> browser
    js --> node
    js --> express

    js --> react
    js --> nextjs
    js --> nuxt
    js --> vue
    js --> rr
    js --> tr

    browser --> Asgardeo
    node --> Asgardeo
    express --> Asgardeo
    react --> Asgardeo
    nextjs --> Asgardeo
    nuxt --> Asgardeo
    vue --> Asgardeo
    rr --> Asgardeo
    tr --> Asgardeo

    react --> samples
    nextjs --> samples
    vue --> samples
    node --> samples
    express --> samples

    samples --> Asgardeo

    %% Click Events
    click pnpm "https://github.com/asgardeo/javascript/blob/main/pnpm-workspace.yaml"
    click nx "https://github.com/asgardeo/javascript/blob/main/nx.json"
    click workflows "https://github.com/asgardeo/javascript/tree/main/.github/workflows"
    click docs "https://github.com/asgardeo/javascript/tree/main/docs/"
    click i18n "https://github.com/asgardeo/javascript/tree/main/packages/i18n/"
    click js "https://github.com/asgardeo/javascript/tree/main/packages/javascript/"
    click browser "https://github.com/asgardeo/javascript/tree/main/packages/browser/"
    click node "https://github.com/asgardeo/javascript/tree/main/packages/node/"
    click express "https://github.com/asgardeo/javascript/tree/main/packages/express/"
    click react "https://github.com/asgardeo/javascript/tree/main/packages/react/"
    click nextjs "https://github.com/asgardeo/javascript/tree/main/packages/nextjs/"
    click nuxt "https://github.com/asgardeo/javascript/tree/main/packages/nuxt/"
    click vue "https://github.com/asgardeo/javascript/tree/main/packages/vue/"
    click rr "https://github.com/asgardeo/javascript/tree/main/packages/react-router/"
    click tr "https://github.com/asgardeo/javascript/tree/main/packages/tanstack-router/"
    click samples "https://github.com/asgardeo/javascript/tree/main/samples/"

    %% Styles
    classDef root fill:#f2f2f2,stroke:#999,stroke-width:1px
    classDef core fill:#d0e7ff,stroke:#1f78b4,stroke-width:1px
    classDef env fill:#d6f5d6,stroke:#33a02c,stroke-width:1px
    classDef framework fill:#ffecd1,stroke:#ff7f00,stroke-width:1px
    classDef apps fill:#fde0dd,stroke:#e31a1c,stroke-width:1px
    classDef external fill:#f9e0ec,stroke:#b15928,stroke-width:1px
    classDef ci fill:#fff3b0,stroke:#ffbf00,stroke-width:1px
    classDef docs fill:#e8daef,stroke:#9b59b6,stroke-width:1px
```
