zod: Architecture

Architecture health: 54/100 (F)

Overview

zod is a JavaScript/TypeScript pnpm project, built with React, Next.js, and Vite. It runs as a frontend (.), backed by 8 shared packages. It stores data in Drizzle and calls OpenAI and Vercel AI SDK across an explicit AI provider boundary. The main structural risks to watch: 12 oversized "god" files and 1 circular import chain. The file with the widest blast radius is packages/zod/src/v4/core/util.ts: 82 files depend on it at runtime; part of an import cycle; oversized and doing too much.

_This entire analysis runs on your machine with no AI required. Connect a model provider to also narrate the reasoning and recover decisions._

Where to start

1. packages/zod/src/v4/index.ts Core module: 115 other modules depend on it, so it shapes much of the system.
2. packages/zod/src/v4/core/util.ts Core module: 85 other modules depend on it, so it shapes much of the system.
3. packages/zod/src/v4/core/errors.ts Core module: 74 other modules depend on it, so it shapes much of the system.
4. packages/zod/src/v4/core/checks.ts Core module: 70 other modules depend on it, so it shapes much of the system.
5. scripts/triage-signal.ts Key flow: Authentication, a high-risk path that enters at invoke triage-signal.ts (scripts/triage-signal.ts).
6. packages/docs/loaders/get-llm-text.ts Key flow: AI provider call, a high-risk path that enters at invoke get-llm-text.ts (packages/docs/loaders/get-llm-text.ts).
7. scripts/check-comments.ts Key flow: File changes / writes, a high-risk path that enters at invoke check-comments.ts (scripts/check-comments.ts).
8. packages/bench/metabench.ts Change with care: 46 files depend on it at runtime.

System map

flowchart TD
  subgraph sys_boundary["zod"]
    node["."]
    benchmarks["benchmarks"]
    docs["docs"]
    integration["integration"]
    mini["mini"]
    resolution["resolution"]
    treeshaking["treeshaking"]
    tsc_perftest["tsc-perftest"]
    zod["zod"]
    store_drizzle[("Drizzle")]
  end
  subgraph ai_boundary["AI Provider Boundary"]
    ai_openai{{"OpenAI"}}
    ai_vercel_ai_sdk{{"Vercel AI SDK"}}
  end
  benchmarks -->|uses| zod
  docs -->|uses| node
  integration -->|uses| zod
  integration -->|uses| mini
  mini -->|uses| zod
  mini -->|uses| node
  resolution -->|uses| mini
  resolution -->|uses| zod
  resolution -->|uses| node
  treeshaking -->|uses| zod
  tsc_perftest -->|uses| zod
  zod -->|uses| node
  node -->|uses| zod
  class node frontend
  class benchmarks library
  class docs library
  class integration library
  class mini library
  class resolution library
  class treeshaking library
  class tsc_perftest library
  class zod library
  class store_drizzle store
  class ai_openai aiprovider
  class ai_vercel_ai_sdk aiprovider
  classDef frontend fill:#2563eb,stroke:#93c5fd,color:#fff,stroke-width:2px;
  classDef service fill:#059669,stroke:#6ee7b7,color:#fff,stroke-width:2px;
  classDef store fill:#d97706,stroke:#fcd34d,color:#fff,stroke-width:2px;
  classDef queue fill:#9333ea,stroke:#d8b4fe,color:#fff,stroke-width:2px;
  classDef job fill:#4f46e5,stroke:#a5b4fc,color:#fff,stroke-width:2px;
  classDef external fill:#475569,stroke:#cbd5e1,color:#fff,stroke-width:2px;
  classDef aiprovider fill:#e11d48,stroke:#fda4af,color:#fff,stroke-width:2px;
  classDef library fill:#0891b2,stroke:#67e8f9,color:#fff,stroke-width:2px;
  classDef cli fill:#0d9488,stroke:#5eead4,color:#fff,stroke-width:2px;
  classDef user fill:#64748b,stroke:#e2e8f0,color:#fff,stroke-width:2px;
  classDef muted fill:#334155,stroke:#64748b,color:#cbd5e1,stroke-width:1px;

Critical flows

Authentication high risk

Entry: invoke triage-signal.ts (scripts/triage-signal.ts)

writes files to the working tree (disk); calls an external service (external API); returns a response to the caller (client)

Authentication guards every protected resource; a regression here can expose data or grant unauthorized access.

sequenceDiagram
  actor C0 as Caller
  participant F0 as triage-signal.ts
  participant Disk as disk
  participant External as external API
  C0->>F0: invoke triage-signal.ts
  F0->>Disk: writes files to the working tree
  F0->>External: calls an external service
  F0-->>C0: returns a response to the caller

AI provider call high risk

Entry: invoke get-llm-text.ts (packages/docs/loaders/get-llm-text.ts)

Provider calls cost money and shape model output; mistakes leak prompts, burn budget, or route to the wrong model.

sequenceDiagram
  actor C0 as Caller
  participant F0 as get-llm-text.ts
  participant F1 as llms-full.txt/route.ts
  participant F2 as llms.txt/route.ts
  C0->>F0: invoke get-llm-text.ts

File changes / writes high risk

Entry: invoke check-comments.ts (scripts/check-comments.ts)

writes files to the working tree (disk); calls an external service (external API); returns a response to the caller (client)

Direct writes to the working tree are hard to reverse; an unguarded write can clobber user code.

sequenceDiagram
  actor C0 as Caller
  participant F0 as check-comments.ts
  participant F1 as reindex.mjs
  participant F2 as triage-signal.ts
  participant F3 as update-iso-4217.ts
  participant F4 as write-stub-package-jsons.ts
  participant Disk as disk
  participant External as external API
  C0->>F0: invoke check-comments.ts
  F0->>Disk: writes files to the working tree
  F1->>Disk: writes files to the working tree
  F2->>Disk: writes files to the working tree
  F2->>External: calls an external service
  F2-->>C0: returns a response to the caller
  F3->>Disk: writes files to the working tree
  F3->>External: calls an external service
  F4->>Disk: writes files to the working tree

Fragile zones

• packages/zod/src/v4/core/util.ts (score 173.3): 82 files depend on it at runtime; part of an import cycle; oversized and doing too much
• packages/bench/metabench.ts (score 92.3): 46 files depend on it at runtime
• packages/zod/src/v4/core/errors.ts (score 79.5): 5 files depend on it at runtime; types used by 69 modules
• packages/zod/src/v4/core/checks.ts (score 77.8): 3 files depend on it at runtime; types used by 67 modules; oversized and doing too much
• packages/zod/src/index.ts (score 60.3): 30 files depend on it at runtime
• packages/bench/benchUtil.ts (score 42.3): 21 files depend on it at runtime
• packages/zod/src/v4/index.ts (score 40.5): 20 files depend on it at runtime
• packages/zod/src/v4/core/schemas.ts (score 32.8): 9 files depend on it at runtime; types used by 9 modules; oversized and doing too much
• packages/zod/src/v4/core/core.ts (score 27.3): 10 files depend on it at runtime; part of an import cycle
• packages/bench/memory/harness.ts (score 26): 13 files depend on it at runtime
• packages/zod/src/v4/core/compile.ts (score 25.5): 10 files depend on it at runtime; oversized and doing too much
• packages/zod/src/mini/index.ts (score 23.3): 11 files depend on it at runtime

Architecture rules