# zitadel/typescript architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Turborepo-powered monorepo containing:
- A full-stack Next.js application (`apps/login`) that implements a customizable ZITADEL login UI.
- Shared TypeScript packages (`@zitadel/client`, `@zitadel/proto`, config presets, ESLint/Prettier/Tailwind).
- An acceptance-test suite including mock Identity Providers (OIDC, SAML) and a “sink” service for email/SMS.
- Purpose: Enable you to develop, test, and ship a ZITADEL-compliant login UI with gRPC/Connect RPC, OIDC flows, MFA, SAML, OAuth, and more.

##### File Structure
- Top-level dirs
- `apps/login`: Next.js 13 app with App Router, UI pages, React components, server/edge functions.
- `packages/*`: Shared client libs, proto defs, config presets.
- `acceptance`: Docker/Go IDP mocks, Sink service, Playwright/Cypress test specs.
- CI/CD configs (`.github/workflows`), Docker files, Changesets, pnpm workspace, Turbo config.
- Architectural patterns
- Monorepo with Turborepo tasks and PNPM workspaces.
- Frontend SSR/ISR via Next.js, with serverless function endpoints under `src/lib/server`.
- Shared code layers: client abstraction (`@zitadel/client`), proto definitions, config layer.
- Acceptance environment orchestrated by Docker Compose, spinning up ZITADEL, mock providers, sink, and running end-to-end tests.

##### README for Additional Insights
- Confirms a “login UI” Next.js application using ZITADEL Session API and OIDC flows.
- Describes features: local registration, external IDPs, MFA factors, password flows, etc.
- Mentions tooling: gRPC stub generation (`pnpm generate`), local ZITADEL via Docker Compose (`pnpm run-zitadel`), acceptance sink (`pnpm run-sink`), tests (`pnpm test:acceptance`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Components
    subgraph "Monorepo Components"
        direction TB
        subgraph "Next.js Login App"
            direction TB
            UI["React UI Components"]:::frontend
            Pages["Frontend Pages & App Router"]:::frontend
            Server["Serverless API Routes & Business Logic"]:::server
            UI --> Pages
            Pages --> Server
        end
        subgraph "Shared Libraries"
            direction TB
            Proto["@zitadel/proto"]:::lib
            Client["@zitadel/client"]:::lib
            ESLint["ESLint Config Preset"]:::config
            Prettier["Prettier Config Preset"]:::config
            Tailwind["Tailwind Config Preset"]:::config
            TSConfig["TypeScript Config Preset"]:::config
        end
        subgraph "Tooling & CI/CD"
            direction TB
            CI["CI/CD Workflows"]:::config
            DockerRoot["Production Dockerfile"]:::config
            Turbo["Turborepo Configs"]:::config
            PNPM["PNPM Workspace Definition"]:::config
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ZITADEL["ZITADEL API"]:::external
        IDPs["Third-party IDPs"]:::external
    end

    %% Acceptance Test Environment
    subgraph "Acceptance Test Environment"
        direction TB
        Compose["Acceptance Test Suite Docker Compose"]:::test
        OIDCMock["Mock OIDC Identity Provider Service"]:::test
        SAMLMock["Mock SAML Identity Provider Service"]:::test
        Sink["Sink Service for Email/SMS Capture"]:::test
        Tests["End-to-End Test Specs (Cypress/Playwright)"]:::test
        AppTests["App-specific Cypress Tests"]:::test
        Compose --> OIDCMock
        Compose --> SAMLMock
        Compose --> Sink
        Tests --> Compose
        AppTests --> Compose
    end

    %% User Flow
    User["User Browser"]:::external
    User -->|"interacts with"| UI
    UI -->|"calls"| Server
    Server -->|"uses RPC client"| Client
    Client -->|"based on protos"| Proto
    Server -->|"calls"| ZITADEL
    ZITADEL -->|"redirects to/callback from"| IDPs

    %% Testing Flow
    Tests -->|"drives browser against"| UI
    Tests -->|"verifies Server endpoints"| Server

    %% Click events
    click UI "https://github.com/zitadel/typescript/tree/main/apps/login/src/components"
    click Pages "https://github.com/zitadel/typescript/tree/main/apps/login/src/app"
    click Server "https://github.com/zitadel/typescript/tree/main/apps/login/src/lib/server"
    click Client "https://github.com/zitadel/typescript/tree/main/packages/zitadel-client"
    click Proto "https://github.com/zitadel/typescript/tree/main/packages/zitadel-proto"
    click ESLint "https://github.com/zitadel/typescript/tree/main/packages/zitadel-eslint-config"
    click Prettier "https://github.com/zitadel/typescript/tree/main/packages/zitadel-prettier-config"
    click Tailwind "https://github.com/zitadel/typescript/tree/main/packages/zitadel-tailwind-config"
    click TSConfig "https://github.com/zitadel/typescript/tree/main/packages/zitadel-tsconfig"
    click Compose "https://github.com/zitadel/typescript/blob/main/acceptance/docker-compose.yaml"
    click OIDCMock "https://github.com/zitadel/typescript/blob/main/acceptance/idp/oidc/main.go"
    click SAMLMock "https://github.com/zitadel/typescript/blob/main/acceptance/idp/saml/main.go"
    click Sink "https://github.com/zitadel/typescript/blob/main/acceptance/sink/main.go"
    click Tests "https://github.com/zitadel/typescript/tree/main/acceptance/tests"
    click AppTests "https://github.com/zitadel/typescript/tree/main/apps/login/cypress/integration"
    click CI "https://github.com/zitadel/typescript/tree/main/.github/workflows"
    click DockerRoot "https://github.com/zitadel/typescript/tree/main/Dockerfile"
    click Turbo "https://github.com/zitadel/typescript/blob/main/turbo.json"
    click PNPM "https://github.com/zitadel/typescript/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
    classDef server fill:#E8DAEF,stroke:#5B2C6F,stroke-width:2px;
    classDef lib fill:#D5F5E3,stroke:#1D8348,stroke-width:2px;
    classDef config fill:#FDEBD0,stroke:#B9770E,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#943126,stroke-width:2px;
    classDef test fill:#FEF9E7,stroke:#B7950B,stroke-width:2px;
```
