# benlorantfy/nestjs-zod architecture

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

- Interactive diagram: https://gitdiagram.com/benlorantfy/nestjs-zod
- Repository: https://github.com/benlorantfy/nestjs-zod

## Overview

##### Project type and purpose
- This is a **library monorepo** (using pnpm workspaces) containing:
- packages/nestjs-zod: the core NestJS–Zod integration
- packages/z: the extended Zod helper package
- packages/example: a sample NestJS application demonstrating usage
- Its purpose is to publish validation and serialization tools (with OpenAPI support) for NestJS applications.

##### File structure
- Top-level:
- pnpm-workspace.yaml + pnpm-lock.yaml (workspace management)
- .github/workflows (CI/CD pipelines for test/build, release, PR labeling)
- MIGRATION.md, LICENSE, README.md, package.json (root scripts and docs)
- packages/nestjs-zod: source code (pipes, guards, DTO creation, OpenAPI patch), tests, rollup config, jest config
- packages/z: extended Zod schemas, error-mapping, frontend helpers, build/test configs
- packages/example: a NestJS app (controllers, modules, filters), tsconfigs, e2e tests

##### README for architecture insights
- Core features (DTO creation, validation pipe, guard, OpenAPI conversion) indicate these components interact at runtime within a NestJS application.
- Example app shows how modules and controllers integrate with the library.

##### Main components
A. Developer workstation / Local Environment
- pnpm Workspace
- IDE (TypeScript, NestJS, Zod code)
B. Monorepo Structure
- Core Library (`nestjs-zod`)
– Zod DTO generator
– ZodValidationPipe
– ZodGuard
– OpenAPI patch & zodToOpenAPI
– ZodSerializerInterceptor
- Extended Z package (`@nest-zod/z`)
– dateString, password, json, from schema utilities
– error mapping, frontend helpers
- Example Application (`packages/example`)
– NestJS modules, controllers, filters (uses core library)
C. External Dependencies
- Zod (peer dependency)
- @nestjs/core, @nestjs/common, @nestjs/swagger
- NPM Registry
D. CI/CD
- GitHub Actions workflows
– test-and-build
– release
– pr-labeler
- Rollup (bundling)
- Jest (unit/integration tests)
E. Publish & Consumption
- npm publish of core and Z packages
- Developers consuming via `npm install nestjs-zod zod @nest-zod/z`

##### Relationships and data flow
- Developer → (code changes) → monorepo
- Monorepo → (pnpm install, build scripts) → compiled artifacts
- CI workflows → (run tests + build) → validate & publish
- Example app → (imports) → core library + Z package → at runtime
- Core library → (calls into) → Zod for schema parsing & validation
- Core library → (patches) → @nestjs/swagger to generate OpenAPI
- Z package → (provides) → custom Zod schemas & frontend utilities

##### Architectural patterns and principles
- **Monorepo with workspaces**: shared tooling, versioning, cross-package dependencies
- **Library–consumer**: clear separation between library code (reusable components) and example usage
- **Plug-in style**: NestJS pipes, guards, interceptors registered via dependency injection
- **Build/Test/Release pipeline**: reproducible builds, automated publishing

##### Final checklist
- Clear component names, roles, and interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Layer
    subgraph "Developer Layer"
        D["Developer IDE & Terminal"]:::dev
    end

    %% Repository Layer
    subgraph "Repository Layer"
        MR["Monorepo Root"]:::repo
        PW["pnpm-workspace.yaml"]:::repo
        RootPkg["package.json / README.md / LICENSE / MIGRATION.md"]:::repo

        subgraph "Core Library (nestjs-zod)" 
            CL_Index["index.ts"]:::package
            CL_DTO["dto.ts"]:::package
            CL_Pipe["pipe.ts"]:::package
            CL_Guard["guard.ts"]:::package
            CL_Serializer["serializer.ts"]:::package
            CL_Exception["exception.ts"]:::package
            subgraph "OpenAPI Integration"
                CL_Patch["patch.ts"]:::package
                CL_Z2O["zod-to-openapi.ts"]:::package
                CL_OIndex["index.ts"]:::package
            end
            CL_Shared["shared/types.ts"]:::package
            CL_Validate["validate.ts"]:::package
            CL_Rollup["rollup.config.js"]:::config
            CL_Jest["jest.config.js"]:::config
        end

        subgraph "Extended Z Package (@nest-zod/z)"
            Z_Index["index.ts"]:::package
            subgraph "Error Mapping"
                Z_ErrorDate["date-string.ts"]:::package
                Z_ErrorPass["password.ts"]:::package
                Z_ErrorShared["shared.ts"]:::package
                Z_ErrorIndex["index.ts"]:::package
            end
            subgraph "Generic Helpers"
                Z_From["from.ts"]:::package
                Z_Json["json.ts"]:::package
                Z_GIndex["index.ts"]:::package
            end
            Z_Frontend["frontend/index.ts"]:::package
            subgraph "Issues"
                Z_IssDate["date-string.ts"]:::package
                Z_IssPass["password.ts"]:::package
                Z_IssOver["overrided.ts"]:::package
                Z_IssIndex["index.ts"]:::package
            end
            subgraph "New Types"
                Z_NewDate["date-string.ts"]:::package
                Z_NewPass["password.ts"]:::package
            end
            Z_Rollup["rollup.config.js"]:::config
            Z_Jest["jest.config.js"]:::config
        end

        subgraph "Example Application"
            EA_Main["main.ts"]:::app
            EA_AppMod["app.module.ts"]:::app
            EA_AppCtrl["app.controller.ts"]:::app
            EA_AppSvc["app.service.ts"]:::app
            EA_PostsCtrl["posts.controller.ts"]:::app
            EA_PostsMod["posts.module.ts"]:::app
            EA_Filter["http-exception.filter.ts"]:::app
            EA_TSConfig["tsconfig.json / tsconfig.build.json / nest-cli.json"]:::config
            EA_E2E["e2e tests & jest-e2e.json"]:::test
        end
    end

    %% CI/CD Layer
    subgraph "CI/CD Workflows" 
        CI_Test["test-and-build.yml"]:::ci
        CI_Release["release.yml"]:::ci
        CI_Label["pr-labeler.yml"]:::ci
        Rollup["Rollup Bundling"]:::ci
        Jest["Jest Testing"]:::ci
    end

    %% Registry Layer
    NPM["npm Registry"]:::registry

    %% External Dependencies
    EX["Peer Dependencies: Zod, @nestjs/core, @nestjs/common, @nestjs/swagger"]:::external

    %% Relationships
    D -->|edits code| PW
    D -->|edits docs| RootPkg
    D -->|runs| MR

    MR -->|contains| PW
    MR -->|contains| RootPkg
    MR -->|workspace includes| CL_Index
    MR -->|workspace includes| Z_Index
    MR -->|workspace includes| EA_Main

    EA_Main -->|imports| CL_Index
    EA_Main -->|imports| Z_Index
    CL_Pipe -->|calls| Z_Index
    CL_Guard -->|uses| Z_Index
    CL_Patch -->|patches| EX
    CL_Z2O -->|converts| EX

    MR -->|triggers| CI_Test
    CI_Test -->|runs| Jest
    CI_Test -->|bundles| Rollup
    MR -->|triggers| CI_Release
    MR -->|triggers| CI_Label

    Rollup -->|publishes| NPM
    CI_Release -->|publishes| NPM

    EA_Main -->|runtime uses| EX

    %% Click Events
    click PW "https://github.com/benlorantfy/nestjs-zod/blob/main/pnpm-workspace.yaml"
    click RootPkg "https://github.com/benlorantfy/nestjs-zod/blob/main/package.json"
    click RootPkg "https://github.com/benlorantfy/nestjs-zod/blob/main/README.md"
    click RootPkg "https://github.com/benlorantfy/nestjs-zod/tree/main/LICENSE"
    click RootPkg "https://github.com/benlorantfy/nestjs-zod/blob/main/MIGRATION.md"

    click CI_Test "https://github.com/benlorantfy/nestjs-zod/blob/main/.github/workflows/test-and-build.yml"
    click CI_Release "https://github.com/benlorantfy/nestjs-zod/blob/main/.github/workflows/release.yml"
    click CI_Label "https://github.com/benlorantfy/nestjs-zod/blob/main/.github/workflows/pr-labeler.yml"

    click CL_Index "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/index.ts"
    click CL_DTO "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/dto.ts"
    click CL_Pipe "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/pipe.ts"
    click CL_Guard "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/guard.ts"
    click CL_Serializer "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/serializer.ts"
    click CL_Exception "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/exception.ts"
    click CL_Patch "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/openapi/patch.ts"
    click CL_Z2O "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/openapi/zod-to-openapi.ts"
    click CL_OIndex "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/openapi/index.ts"
    click CL_Shared "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/shared/types.ts"
    click CL_Validate "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/src/validate.ts"
    click CL_Rollup "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/rollup.config.js"
    click CL_Jest "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/nestjs-zod/jest.config.js"

    click Z_Index "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/index.ts"
    click Z_ErrorDate "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/error-map/date-string.ts"
    click Z_ErrorPass "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/error-map/password.ts"
    click Z_ErrorShared "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/error-map/shared.ts"
    click Z_ErrorIndex "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/error-map/index.ts"
    click Z_From "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/generic-types/from.ts"
    click Z_Json "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/generic-types/json.ts"
    click Z_GIndex "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/generic-types/index.ts"
    click Z_Frontend "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/frontend/index.ts"
    click Z_IssDate "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/issues/date-string.ts"
    click Z_IssPass "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/issues/password.ts"
    click Z_IssOver "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/issues/overrided.ts"
    click Z_IssIndex "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/issues/index.ts"
    click Z_NewDate "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/new-types/date-string.ts"
    click Z_NewPass "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/src/z/new-types/password.ts"
    click Z_Rollup "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/rollup.config.js"
    click Z_Jest "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/z/jest.config.js"

    click EA_Main "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/main.ts"
    click EA_AppMod "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/app.module.ts"
    click EA_AppCtrl "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/app.controller.ts"
    click EA_AppSvc "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/app.service.ts"
    click EA_PostsCtrl "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/posts/posts.controller.ts"
    click EA_PostsMod "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/posts/posts.module.ts"
    click EA_Filter "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/src/http-exception.filter.ts"
    click EA_TSConfig "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/tsconfig.json"
    click EA_TSConfig "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/tsconfig.build.json"
    click EA_TSConfig "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/nest-cli.json"
    click EA_E2E "https://github.com/benlorantfy/nestjs-zod/blob/main/packages/example/test/app.e2e-spec.ts"

    %% Styles
    classDef dev fill:#f5f5dc,stroke:#333,stroke-width:1px
    classDef repo fill:#e0f7fa,stroke:#333,stroke-width:1px
    classDef package fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef app fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef config fill:#d7ccc8,stroke:#333,stroke-width:1px
    classDef test fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef ci fill:#ffcc80,stroke:#333,stroke-width:1px
    classDef registry fill:#a5d6a7,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
```
