# zitadel/zitadel-nextjs architecture

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

- Interactive diagram: https://gitdiagram.com/zitadel/zitadel-nextjs
- Repository: https://github.com/zitadel/zitadel-nextjs

## Overview

##### Project Type and Purpose
- The project is a full-stack (server-rendered and API-enabled) Next.js application.
- Its primary purpose is to authenticate users via NextAuth.js with Zitadel’s OIDC endpoint and display user information.
- The README clearly indicates that the application shows authentication flow and retrieval of user details, using the authentication code flow (with PKCE) and session state management.

##### Analyzing the File Structure
- Top-level configuration files (.env, next.config.js, package.json, tsconfig.json, ESLint/Prettier config files) suggest a well-configured Next.js setup.
- The “pages” directory contains application routes:
– “pages/_app.tsx” implements the SessionProvider so that session state is shared between pages.
– “pages/index.tsx” serves as the homepage.
– “pages/profile.tsx” serves as the user profile or callback page after authentication.
– “pages/api/auth/[...nextauth].tsx” is the core API route to set up authentication with NextAuth.js and the Zitadel provider.
– “pages/api/userinfo.ts” might provide additional API endpoints for user data fetching if needed.
- The “components” directory (with profile.tsx) likely contains reusable UI components that either display profile info or provide authentication UI elements.
- Additional directories like “public” and “styles” handle static assets and styling respectively.

##### Main Components
a. Frontend/UI:
- Pages: Index, Profile, and other potential pages.
- Components: The profile component and possibly other UI components.
- Session Provider in _app.tsx: Wraps the entire application to share authentication state.

b. API Layer:
- NextAuth API Route (pages/api/auth/[...nextauth].tsx): Configures and manages the authentication flow.
- Additional API endpoints (e.g., pages/api/userinfo.ts) for fetching user details if implemented separately.

c. External Authentication Service:
- Zitadel / OIDC Provider: The external identity provider handling the authentication flow.
- Interaction flow between the NextAuth API route and Zitadel, including exchange of authentication codes, tokens, and user profile data.

##### Relationships and Interactions
- The client/browser interacts with the Next.js front end.
- When a user clicks “Sign in” (as defined in pages/index.tsx), the front end invokes the NextAuth API route.
- The NextAuth API route then redirects the authentication flow to the Zitadel OIDC endpoint.
- Upon successful authentication, Zitadel calls back to the designated redirect URL (e.g., pages/api/auth/callback/zitadel) and returns user profile data.
- The session state is then managed and provided to the UI via the SessionProvider in _app.tsx, which enables seamless sharing of the authenticated state across pages.
- Optionally, the pages/api/userinfo endpoint can be used to fetch up-to-date user details from session data.

##### Important Architectural Patterns and Details to Note
- Separation of Concerns: UI components are distinct from authentication/logic handled in API routes.
- The project uses Next.js API routes as a lightweight backend predominantly for managing authentication.
- Session management is centralized via NextAuth’s SessionProvider, ensuring the authenticated state flows properly between pages.
- Configuration’s dependency on environment variables (like NEXTAUTH_URL, ZITADEL_CLIENT_ID, etc.) which bind the application to a specific Zitadel project configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    Browser["Browser / Client"]:::client

    %% Frontend Layer
    subgraph "Frontend (Next.js)"
        SP["Session Provider (_app.tsx)"]:::frontend
        HP["Home Page (index.tsx)"]:::frontend
        PP["User Profile Page (profile.tsx)"]:::frontend
        PC["Profile UI Component (profile.tsx)"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend APIs"
        AuthAPI["Authentication API ([...nextauth].tsx)"]:::backend
        InfoAPI["User Info API (userinfo.ts)"]:::backend
    end

    %% External Authentication Service
    AuthService["Zitadel/OIDC Endpoint"]:::external

    %% Relationships and Data Flow

    %% Client initiates request to Home Page for sign in
    Browser -->|"Request_Home"| HP

    %% User action triggers sign in from Home Page to Authentication API
    HP -->|"Initiate_SignIn"| AuthAPI

    %% Authentication API redirects to External Auth Service
    AuthAPI -->|"Redirect_to_Zitadel"| AuthService

    %% Zitadel processes and sends callback to Authentication API
    AuthService -->|"Auth_Callback"| AuthAPI

    %% Authentication API establishes session and updates Session Provider
    AuthAPI -->|"Update_Session"| SP

    %% Session Provider enables display of user information on Profile Page
    SP -->|"Render_Profile"| PP

    %% Profile Page may use Profile UI Component for display
    PP -->|"Use_Component"| PC

    %% Optionally, Profile Page/API retrieves up-to-date user info from User Info API
    PP -->|"Fetch_UserInfo"| InfoAPI

    %% Click Events
    click SP "https://github.com/zitadel/zitadel-nextjs/blob/main/pages/_app.tsx"
    click HP "https://github.com/zitadel/zitadel-nextjs/blob/main/pages/index.tsx"
    click PP "https://github.com/zitadel/zitadel-nextjs/blob/main/pages/profile.tsx"
    click AuthAPI "https://github.com/zitadel/zitadel-nextjs/blob/main/pages/api/auth/[...nextauth].tsx"
    click InfoAPI "https://github.com/zitadel/zitadel-nextjs/blob/main/pages/api/userinfo.ts"
    click PC "https://github.com/zitadel/zitadel-nextjs/blob/main/components/profile.tsx"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef client fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
```
