# open-circle/valibot architecture

> Architecture diagram of the GitHub repository open-circle/valibot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-circle/valibot
- Repository: https://github.com/open-circle/valibot

## Overview

Valibot is a modular, type-safe schema library: users define schemas, then validate unknown data to obtain typed output or structured validation results. Its runtime includes schema definitions, validation and transformation actions, and parse interfaces; the README also highlights static type inference and synchronous safe-parse/type-guard APIs. The repository additionally contains Zod-to-Valibot and version-migration codemods, plus a documentation worker that serves Markdown and MCP requests. Source excerpts were limited, so links between unsampled components are omitted.

Main entry points: [`website/worker/index.ts`](https://github.com/open-circle/valibot/blob/main/website/worker/index.ts) (Docs worker), [`library/src/methods/parser/parserAsync.ts`](https://github.com/open-circle/valibot/blob/main/library/src/methods/parser/parserAsync.ts) (Async parser), [`library/src/methods/safeParser/safeParserAsync.ts`](https://github.com/open-circle/valibot/blob/main/library/src/methods/safeParser/safeParserAsync.ts) (Async safe parser), [`library/src/index.ts`](https://github.com/open-circle/valibot/blob/main/library/src/index.ts) (Typed results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Validation library"]
  node_schema["Schema definitions<br/>[index.ts]"]
  node_actions["Validation actions<br/>[index.ts]"]
  node_parser["Async parser<br/>[parserAsync.ts]"]
  node_safeparser["Async safe parser<br/>[safeParserAsync.ts]"]
  node_runtime_result["Typed results<br/>[index.ts]"]
end

subgraph group_migration["Migration tools"]
  node_zod_cli["Zod converter CLI<br/>[cli.mjs]"]
  node_zod_transform["Zod transforms<br/>[index.ts]"]
  node_version_migration["Version migration<br/>[index.ts]"]
end

subgraph group_docs["Documentation delivery"]
  node_docs_worker["Docs worker<br/>[index.ts]"]
  node_static_assets["Static assets"]
  node_markdown["Markdown delivery"]
  node_mcp["MCP endpoint"]
end

node_consumer(("Application code"))
node_site_visitor(("Documentation visitor"))

node_consumer -->|"defines"| node_schema
node_consumer -->|"parses data"| node_parser
node_consumer -->|"safe parses"| node_safeparser
node_parser -->|"returns output"| node_runtime_result
node_safeparser -->|"returns result"| node_runtime_result
node_site_visitor -->|"requests content"| node_docs_worker
node_docs_worker -->|"dispatches MCP"| node_mcp
node_docs_worker -->|"serves Markdown"| node_markdown
node_docs_worker -->|"fetches assets"| node_static_assets

click node_schema "https://github.com/open-circle/valibot/blob/main/library/src/index.ts"
click node_actions "https://github.com/open-circle/valibot/blob/main/library/src/index.ts"
click node_parser "https://github.com/open-circle/valibot/blob/main/library/src/methods/parser/parserAsync.ts"
click node_safeparser "https://github.com/open-circle/valibot/blob/main/library/src/methods/safeParser/safeParserAsync.ts"
click node_runtime_result "https://github.com/open-circle/valibot/blob/main/library/src/index.ts"
click node_zod_cli "https://github.com/open-circle/valibot/blob/main/codemod/zod-to-valibot/cli.mjs"
click node_zod_transform "https://github.com/open-circle/valibot/blob/main/codemod/zod-to-valibot/src/transform/index.ts"
click node_version_migration "https://github.com/open-circle/valibot/blob/main/codemod/migrate-to-v0.31.0/src/index.ts"
click node_docs_worker "https://github.com/open-circle/valibot/blob/main/website/worker/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schema,node_actions,node_parser,node_safeparser,node_runtime_result toneBlue
class node_zod_cli,node_zod_transform,node_version_migration toneAmber
class node_docs_worker,node_static_assets,node_markdown,node_mcp toneMint
class node_consumer,node_site_visitor toneIndigo
```

## Components

### Validation library

- [Schema definitions](https://github.com/open-circle/valibot/blob/main/library/src/index.ts): `library/src/index.ts`
- [Validation actions](https://github.com/open-circle/valibot/blob/main/library/src/index.ts): `library/src/index.ts`
- [Async parser](https://github.com/open-circle/valibot/blob/main/library/src/methods/parser/parserAsync.ts): `library/src/methods/parser/parserAsync.ts`
- [Async safe parser](https://github.com/open-circle/valibot/blob/main/library/src/methods/safeParser/safeParserAsync.ts): `library/src/methods/safeParser/safeParserAsync.ts`
- [Typed results](https://github.com/open-circle/valibot/blob/main/library/src/index.ts): `library/src/index.ts`

### Migration tools

- [Zod converter CLI](https://github.com/open-circle/valibot/blob/main/codemod/zod-to-valibot/cli.mjs): `codemod/zod-to-valibot/cli.mjs`
- [Zod transforms](https://github.com/open-circle/valibot/blob/main/codemod/zod-to-valibot/src/transform/index.ts): `codemod/zod-to-valibot/src/transform/index.ts`
- [Version migration](https://github.com/open-circle/valibot/blob/main/codemod/migrate-to-v0.31.0/src/index.ts): `codemod/migrate-to-v0.31.0/src/index.ts`

### Documentation delivery

- [Docs worker](https://github.com/open-circle/valibot/blob/main/website/worker/index.ts): `website/worker/index.ts`
- **Static assets**
- **Markdown delivery**
- **MCP endpoint**

### Other components

- **Application code**
- **Documentation visitor**

## Connections

- Application code → Schema definitions: defines
- Application code → Async parser: parses data
- Application code → Async safe parser: safe parses
- Async parser → Typed results: returns output
- Async safe parser → Typed results: returns result
- Documentation visitor → Docs worker: requests content
- Docs worker → MCP endpoint: dispatches MCP
- Docs worker → Markdown delivery: serves Markdown
- Docs worker → Static assets: fetches assets