# kinde-oss/kinde-auth-nextjs architecture

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

- Interactive diagram: https://gitdiagram.com/kinde-oss/kinde-auth-nextjs
- Repository: https://github.com/kinde-oss/kinde-auth-nextjs

## Overview

##### Project Type and Purpose
- This is a NextJS SDK package (“Kinde NextJS”) designed to simplify authentication and session management with the Kinde identity platform.
- It ships as an NPM package, exposes both server-side helpers (middleware, API handlers, session managers) and client-side React hooks/components.
- A “playground” NextJS App Router sample app shows how to consume the SDK via `npm link` and exercise its auth flows.

##### Key Directories and Their Roles
- `/src` – The core SDK code, subdivided into:
- api-client.js – low-level HTTP client for talking to Kinde’s API
- authMiddleware/ – Express-style middleware to protect API routes
- handlers/ – NextJS API route handler implementations (login, logout, callback, etc.)
- frontend/ – React providers, hooks, component factories, utils for in-browser auth
- session/ – Helpers to read/write tokens, flags, permissions, users from session store
- middleware/ – NextJS middleware integration point
- utils/ – Utility functions (cookie ops, JWT validation, URL generators)
- routerClients/ – Abstractions for NextJS App vs Pages Router
- server/ – Shared entry point for server code
- `/playground` – A NextJS App Router example app using the SDK:
- `/app/api/auth/[...kindeAuth]` – API routes orchestrating the OAuth flow
- `/app/dashboard`, `/app/protect` – Sample protected pages
- `AuthProvider.tsx` – React context provider from SDK
- Config & Tooling root:
- rollup.config.mjs – Bundler config for packaging the SDK
- jest.config.mjs, vitest.config.ts – Testing setup
- .github/workflows – CI (build, test) and publish pipelines
- pnpm-workspace.yaml – Monorepo management

a. Main Components
- SDK Package
- Client-side layer: React Provider, hooks, components
- Server-side layer: NextJS middleware, API handlers, session managers
- Utilities: cookie management, JWT validation, router clients
- Playground NextJS App
- Frontend pages (protected vs. public)
- API routes that delegate to SDK handlers
- Env config (.env.local) containing Kinde credentials
- External Service
- Kinde Auth API (OAuth endpoints, token introspection, user info)
- CI/CD Pipeline
- GitHub Actions for linting, unit tests, bundle, release to NPM

b. Relationships & Data Flow
- User → Playground Frontend (React app)
- On first load, AuthProvider initializes session (reads cookies)
- For protected pages, React hooks call SDK’s client or redirect to login
- Playground Frontend → Playground API Routes
- Calls `/api/auth/login`, `/api/auth/callback`, `/api/protected`
- NextJS routes use SDK handlers (in src/handlers)
- SDK Handlers → Kinde Auth API
- Redirect user to Kinde’s OAuth endpoint
- On callback, exchange code for tokens, set cookies
- Subsequent requests → NextJS Middleware (src/middleware)
- Validates session via cookies or introspection
- Populates request context or rejects
- CI/CD → GitHub Actions
- On push: run lint, tests (Jest/Vitest), build (Rollup)
- On release tag: publish to NPM

c. Architectural Patterns & Principles
- Modular separation of client vs. server concerns
- NextJS App Router conventions (middleware, `app/api`, React Server Components)
- Dependency Injection via React Context (AuthProvider)
- Single source of truth for session state (cookies + in-memory)
- Abstraction over routing (AppRouter vs. PagesRouter)

d. Key Technologies
- NextJS (App Router)
- React + TypeScript
- Rollup for ESM bundling
- Jest & Vitest for testing
- PNPM workspace for monorepo
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Playground NextJS App
    subgraph "Playground NextJS App" 
        direction TB
        subgraph "Frontend Pages" 
            direction TB
            PP1["Public Landing"]:::play
            PP2["Dashboard (Protected)"]:::play
            PP3["Protect (Protected)"]:::play
        end
        subgraph "API Routes" 
            direction TB
            AR1["/api/auth/[...kindeAuth]"]:::play
            AR2["/api/protected"]:::play
            AR3["/api/public"]:::play
        end
        PMW["Playground Middleware"]:::play
        PP1 -->|navigates| AR3
        PP2 -->|calls| AR2
        PP3 -->|calls| AR2
        PMW -->|validates| AR2
    end

    %% SDK Package
    subgraph "SDK Package" 
        direction TB
        subgraph "Client-side Layer" 
            direction TB
            SC1["KindeProvider"]:::sdk
            SC2["OldAuthProvider"]:::sdk
            SC3["use-kinde-browser-client"]:::sdk
            SC4["use-provided-kinde-auth"]:::sdk
            SC5["use-providerless-kinde-auth"]:::sdk
            SC6["use-session-sync"]:::sdk
            SC7["use-sync-state"]:::sdk
            SC8["frontend index & store"]:::sdk
        end
        subgraph "Component Factories" 
            direction TB
            CF1["feature-flag-factory"]:::sdk
            CF2["organization-factory"]:::sdk
            CF3["permissions-factory"]:::sdk
            CF4["token-factory"]:::sdk
        end
        subgraph "Server-side Layer" 
            direction TB
            SS1["authMiddleware"]:::sdk
            SS2["API Handlers"]:::sdk
            SS3["middleware integration"]:::sdk
            SS4["routerClients"]:::sdk
            SS5["server entry"]:::sdk
            SS6["session managers"]:::sdk
        end
        subgraph "Utilities" 
            direction TB
            U1["api-client"]:::sdk
            U2["cookie & JWT utils"]:::sdk
            U3["URL & redirect helpers"]:::sdk
            U4["router detection & cookie setters"]:::sdk
            U5["other utils"]:::sdk
        end
    end

    %% External Kinde Auth
    subgraph "External Service" 
        direction TB
        KAPI["Kinde Auth API"]:::ext
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        CI1["GitHub Actions (build-test-ci)"]:::ci
        CI2["GitHub Actions (release)"]:::ci
        CI3["Rollup Build"]:::ci
        CI4["Jest & Vitest Tests"]:::ci
        CI5["NPM Publish"]:::ci
    end

    %% Flows
    User["User Browser"]:::ext -->|visits| PP1
    User -->|tries protected| PP2
    PP1 -->|init AuthProvider| SC1
    SC1 -->|hooks| U1
    PP2 -->|uses| SC3
    PP2 -->|uses| SC4
    PP2 -->|uses| SC5
    PP2 -->|uses| SC6
    AR1 -->|delegates login/logout| SS2
    AR2 -->|protect| SS2
    SS2 -->|calls| U1
    SS2 -->|redirects| KAPI
    KAPI -->|callback code| SS2
    SS2 -->|sets cookies| U2
    PMW -->|uses| SS1
    SS1 -->|matches paths| U4
    SS1 -->|checks public| U5
    SS1 -->|validates JWT| U2
    SS3 -->|integrates| PMW
    SS4 -->|abstracts router| SS3
    SS5 -->|entry for server| SS2
    CI1 --> CI4
    CI1 --> CI3
    CI1 --> CI2
    CI2 --> CI5

    %% Click events
    click U1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/api-client.js"
    click SS1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/authMiddleware/authMiddleware.ts"
    click SS1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/authMiddleware/isPublicPathMatch.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/auth.js"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/login.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/logout.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/callback.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/endSession.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/createOrg.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/portal.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/protect.js"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/register.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/setup.ts"
    click SS2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/handlers/health.js"
    click SC1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/KindeProvider.tsx"
    click SC2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/OldAuthProvider.jsx"
    click SC3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/hooks/public/use-kinde-browser-client.ts"
    click SC4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/hooks/public/use-provided-kinde-auth.ts"
    click SC5 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/hooks/public/use-providerless-kinde-auth.ts"
    click SC6 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/hooks/internal/use-session-sync.ts"
    click SC7 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/hooks/internal/use-sync-state.tsx"
    click SC8 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/index.js"
    click SC8 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/store.ts"
    click CF1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/factories/feature-flag-factory.ts"
    click CF2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/factories/organization-factory.ts"
    click CF3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/factories/permissions-factory.ts"
    click CF4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/frontend/factories/token-factory.ts"
    click SS6 "https://github.com/kinde-oss/kinde-auth-nextjs/tree/main/src/session/"
    click SS3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/middleware/index.js"
    click SS4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/routerClients/AppRouterClient.js"
    click SS4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/routerClients/PagesRouterClient.js"
    click SS4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/routerClients/RouterClient.js"
    click SS5 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/server/index.js"
    click U2 "https://github.com/kinde-oss/kinde-auth-nextjs/tree/main/src/utils/cookies/"
    click U2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/utils/jwt/validation.ts"
    click U3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/utils/generateCallbackUrl.js"
    click U3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/utils/redirectOnExpiredToken.ts"
    click U4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/utils/isAppRouter.js"
    click U4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/utils/appRouter/setVerifierCookie.js"
    click U4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/src/utils/pageRouter/setVerifierCookie.js"
    click U5 "https://github.com/kinde-oss/kinde-auth-nextjs/tree/main/src/utils/"
    click PP1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/page.tsx"
    click PP2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/dashboard/page.tsx"
    click PP3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/protect/page.tsx"
    click AR1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/api/auth/[...kindeAuth]/route.ts"
    click AR2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/api/protected/route.ts"
    click AR3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/api/public/route.ts"
    click PMW "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/middleware.ts"
    click SC1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/playground/src/app/AuthProvider.tsx"
    click CI1 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/.github/workflows/build-test-ci.yml"
    click CI2 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/.github/workflows/release.yml"
    click CI3 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/rollup.config.mjs"
    click CI4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/jest.config.mjs"
    click CI4 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/vitest.config.ts"
    click CI5 "https://github.com/kinde-oss/kinde-auth-nextjs/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef play fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef sdk fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef ext fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef ci fill:#eceff1,stroke:#90a4ae,color:#37474f
```
