# ehwplus/zitadel-nodejs-nestjs architecture

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

- Interactive diagram: https://gitdiagram.com/ehwplus/zitadel-nodejs-nestjs
- Repository: https://github.com/ehwplus/zitadel-nodejs-nestjs

## Overview

##### Main Components
- NestJS Application: Represented by the “src” folder. This includes the primary application modules (app.module.ts), controllers (app.controller.ts), and entry point (main.ts).
- Zitadel Authentication Library: The “libs/zitadel-auth” folder is dedicated to the Zitadel authentication integration. It contains key modules, interfaces, strategies (using Passport), and module definitions specific to Zitadel.
- Configuration & Environment: Important configuration files and environment files (like .env.sample) are critical to the setup and deployment of the authentication flow.

##### Relationships and Interactions
- The NestJS application invokes the Zitadel authentication module (from libs/zitadel-auth) when handling authentication requests.
- The Passport strategy defined in libs/zitadel-auth (zitadel.strategy.ts) manages the interaction with the external Zitadel OIDC endpoints to facilitate login flows.
- Environment variables (populated from the .env file) configure client IDs, secrets, and other Zitadel-specific parameters.
- Any results from the authentication process are then handled by the NestJS controllers/services.

##### Architectural Patterns and Design Principles
- Modular Architecture: The code is structured into separate modules (e.g., the application module in “src” and the separate authentication library in “libs”), which hints at a clean separation of concerns.
- Passport Integration & Strategy Pattern: Using Passport for authentication with a custom strategy to liaise with Zitadel.
- Configuration-as-Code: The reliance on environmental configurations and dedicated config files (.env, tsconfig files, etc.) ensures a flexible, environment-specific setup.

##### Relevant Technologies
- NestJS: The primary backend framework.
- Passport: For managing authentication strategies.
- TypeScript: Evident from all the “.ts” files and tsconfig configurations.
- Zitadel: The external authentication provider.
- Potential tooling and linting frameworks such as ESLint and Prettier are used for code quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Nodes
    Client["Client Request"]:::client
    Config["Configuration (.env sample)"]:::config
    Zitadel["Zitadel OIDC Provider"]:::external

    %% NestJS Application Subgraph
    subgraph "NestJS Application"
        A1["app.module.ts"]:::nestjs
        A2["app.controller.ts"]:::nestjs
        A3["main.ts"]:::nestjs
    end

    %% Zitadel Authentication Library Subgraph
    subgraph "Zitadel Authentication Library"
        Z1["zitadel-auth.module.ts"]:::auth
        Z2["zitadel-auth.module-definition.ts"]:::auth
        Z3["Passport Strategy"]:::strategy
    end

    %% Data Flow Connections
    Client -->|"sendsRequest"| A2
    Config -->|"configures"| A2
    Config -->|"configures"| Z1
    A2 -->|"invokesAuth"| Z1
    Z1 -->|"uses"| Z3
    Z3 -->|"callsOIDC"| Zitadel
    Zitadel -->|"returnsTokens"| Z1
    Z1 -->|"sendsResponse"| A2
    A2 -->|"responds"| Client

    %% Click Events
    click A1 "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/src/app.module.ts"
    click A2 "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/src/app.controller.ts"
    click A3 "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/src/main.ts"
    click Z1 "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/libs/zitadel-auth/src/zitadel-auth.module.ts"
    click Z2 "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/libs/zitadel-auth/src/zitadel-auth.module-definition.ts"
    click Z3 "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/libs/zitadel-auth/src/strategy/zitadel.strategy.ts"
    click Config "https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/.env.sample"

    %% Styles
    classDef nestjs fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef auth fill:#ffeeba,stroke:#333,stroke-width:2px;
    classDef strategy fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef client fill:#fff3cd,stroke:#333,stroke-width:2px;
```
