# vercel-labs/zero architecture

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

- Interactive diagram: https://gitdiagram.com/vercel-labs/zero
- Repository: https://github.com/vercel-labs/zero

## Overview

1. This repository is a multi-part language platform centered on the Zero programming language. The core product is not a single app, but a toolchain: compiler, CLI, standard-library surface, documentation, tests, examples, and editor support.

2. There are two compiler implementations in the repo. `native/zero-c/` is the native compiler/runtime implementation in C, including lexing, parsing, checking, IR, target emission, filesystem/web support, and target manifests. `compiler-zero/` is a Zero-authored compiler codebase that mirrors the same pipeline in `.0` sources and appears to be used as a self-hosting or bootstrapping path.

3. The main language pipeline is conventional but language-specific: source files are lexed, parsed, type-checked, lowered into an intermediate representation, and then emitted for different targets. The native compiler directory makes that split explicit with modules like lexer, parser, checker, MIR/IR, runtime, and WASM/backend emitters.

4. The CLI is the primary user-facing boundary. The README shows commands like `zero check`, `zero run`, `zero build`, `zero graph`, `zero size`, `zero routes`, and `zero doctor`. That means the CLI is both a compiler front-end and a project/package inspection tool, not just a build command.

5. Packages and manifests are a first-class architectural boundary. Many examples and conformance fixtures contain `zero.json`, which defines package structure, dependencies, targets, and entry points. The repo therefore models compilation around packages/modules rather than loose single files only.

6. The `examples/` tree is a curated set of runnable language samples organized by feature and application shape: tiny snippets, CLI tools, package/module examples, web examples, C interop, memory/ownership examples, and target-specific demos. These examples serve as both documentation and smoke tests for the language/runtime surface.

7. `conformance/` is the behavior contract layer. It contains pass/fail fixtures for parsing, type checking, diagnostics, native semantics, packaging, and C interop. This is where the repo encodes expected compiler behavior, error shapes, and target restrictions. It is a key boundary between “language spec intent” and implementation.

8. `docs-site/` is a separate web application for the project documentation. It includes article content, doc routing, search, chat, Open Graph image generation, highlighting, and a browser playground. The docs site also embeds a WASM compiler artifact (`public/playground/zeroc-zero.wasm`), so the browser documentation experience is tied directly to a compiled compiler/runtime build.

9. The docs site is not just static content: it has server-side API routes for search and docs chat, and libraries for search indexing, rate limiting, GitHub integration, and Zero WASM loading. That makes it a hybrid content/app layer sitting on top of the language project’s artifacts and metadata.

10. `extensions/vscode/` provides editor integration for `.0` files. The contents are focused on language configuration, syntax highlighting, snippets, and extension tests, so this layer is about developer ergonomics rather than compilation.

11. `scripts/` and `tests/` are the repo’s orchestration and validation layer. Scripts cover native smoke tests, browser/WASM smoke tests, benchmark runs, provenance guardrails, CLI contract checks, and reliability/sanitizer checks. `tests/` adds TypeScript-level CLI tests, indicating the project validates the installed command interface from the outside.

12. The repository is designed around multiple execution targets. Evidence in the tree and fixtures points to native execution, WebAssembly, and target-specific compilation constraints, with separate tests for unsupported targets and compatibility checks. The architecture therefore branches from the compiler into backends rather than assuming one universal runtime.

13. The overall data flow is: user source code and manifests enter through the CLI, the compiler pipeline produces diagnostics or artifacts, target backends emit native/WASM outputs, and the docs site plus examples/conformance fixtures continuously validate and demonstrate the behavior of that toolchain. The repo’s boundaries are organized more by toolchain stage and validation surface than by frontend/backend application layers.

Main entry points: [`native/zero-c`](https://github.com/vercel-labs/zero/tree/main/native/zero-c) (Native compiler), [`docs-site`](https://github.com/vercel-labs/zero/tree/main/docs-site) (Docs site), [`conformance`](https://github.com/vercel-labs/zero/tree/main/conformance) (Conformance), [`examples`](https://github.com/vercel-labs/zero/tree/main/examples) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_toolchain["Toolchain"]
  node_cli["Zero CLI<br/>user command"]
  node_native_compiler["Native compiler<br/>C compiler"]
  node_c_frontend["Lex/parse<br/>front-end<br/>[lexer.c]"]
  node_c_checker["Type check<br/>semantic check<br/>[checker.c]"]
  node_c_ir["IR lower<br/>middle-end<br/>[ir.c]"]
  node_c_backends["Emit targets<br/>backends<br/>[emit_wasm.c]"]
  node_c_platform["Platform IO<br/>runtime support<br/>[fs.c]"]
  node_self_hosted["Self-hosted compiler<br/>Zero sources"]
  node_zh_lexer["Lexer<br/>compiler stage<br/>[lexer.0]"]
  node_zh_parser["Parser<br/>compiler stage<br/>[parser.0]"]
  node_zh_checker["Checker<br/>compiler stage<br/>[checker.0]"]
  node_zh_mir["MIR<br/>compiler stage<br/>[mir.0]"]
  node_zh_wasm["WASM emit<br/>backend<br/>[wasm.0]"]
  node_package_manifests["Package manifests<br/>project model<br/>[zero.json]"]
end

subgraph group_validation["Validation"]
  node_conformance["Conformance<br/>behavior contract"]
  node_scripts["Scripts<br/>orchestration"]
  node_ts_tests["CLI tests<br/>external tests<br/>[zero-cli.test.ts]"]
end

subgraph group_experience["Experience"]
  node_docs_site["Docs site<br/>web app"]
  node_docs_libs["Docs libs<br/>site logic<br/>[search-index.js]"]
  node_playground_wasm[("Playground WASM<br/>compiled artifact<br/>[zeroc-zero.wasm]")]
  node_vscode_ext["VS Code ext<br/>editor integration"]
end

subgraph group_samples["Samples"]
  node_examples["Examples<br/>sample suite"]
end

node_cli -->|"drives"| node_native_compiler
node_cli -->|"reads"| node_package_manifests
node_native_compiler -->|"starts with"| node_c_frontend
node_c_frontend -->|"feeds"| node_c_checker
node_c_checker -->|"lowers to"| node_c_ir
node_c_ir -->|"emits"| node_c_backends
node_c_platform -->|"supports"| node_native_compiler
node_self_hosted -->|"contains"| node_zh_lexer
node_zh_lexer -->|"feeds"| node_zh_parser
node_zh_parser -->|"feeds"| node_zh_checker
node_zh_checker -->|"lowers to"| node_zh_mir
node_zh_mir -->|"emits"| node_zh_wasm
node_package_manifests -->|"organizes"| node_examples
node_package_manifests -->|"anchors"| node_conformance
node_examples -.->|"mirrors"| node_conformance
node_conformance -->|"validates"| node_native_compiler
node_docs_site -->|"uses"| node_docs_libs
node_docs_site -->|"embeds"| node_playground_wasm
node_docs_site -->|"documents"| node_examples
node_vscode_ext -->|"supports"| node_examples
node_scripts -->|"smokes"| node_native_compiler
node_scripts -->|"smokes"| node_docs_site
node_scripts -->|"runs"| node_conformance
node_ts_tests -->|"asserts"| node_cli

click node_cli "https://github.com/vercel-labs/zero/tree/main/bin/zero"
click node_native_compiler "https://github.com/vercel-labs/zero/tree/main/native/zero-c"
click node_c_frontend "https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/lexer.c"
click node_c_checker "https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/checker.c"
click node_c_ir "https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/ir.c"
click node_c_backends "https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/emit_wasm.c"
click node_c_platform "https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/fs.c"
click node_self_hosted "https://github.com/vercel-labs/zero/tree/main/compiler-zero"
click node_zh_lexer "https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/lexer.0"
click node_zh_parser "https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/parser.0"
click node_zh_checker "https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/checker.0"
click node_zh_mir "https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/mir.0"
click node_zh_wasm "https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/wasm.0"
click node_package_manifests "https://github.com/vercel-labs/zero/blob/main/examples/web/hello/zero.json"
click node_examples "https://github.com/vercel-labs/zero/tree/main/examples"
click node_conformance "https://github.com/vercel-labs/zero/tree/main/conformance"
click node_docs_site "https://github.com/vercel-labs/zero/tree/main/docs-site"
click node_docs_libs "https://github.com/vercel-labs/zero/blob/main/docs-site/lib/search-index.js"
click node_playground_wasm "https://github.com/vercel-labs/zero/blob/main/docs-site/public/playground/zeroc-zero.wasm"
click node_vscode_ext "https://github.com/vercel-labs/zero/tree/main/extensions/vscode"
click node_scripts "https://github.com/vercel-labs/zero/tree/main/scripts"
click node_ts_tests "https://github.com/vercel-labs/zero/blob/main/tests/zero-cli.test.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_cli,node_native_compiler,node_c_frontend,node_c_checker,node_c_ir,node_c_backends,node_c_platform,node_self_hosted,node_zh_lexer,node_zh_parser,node_zh_checker,node_zh_mir,node_zh_wasm,node_package_manifests toneBlue
class node_conformance,node_scripts,node_ts_tests toneAmber
class node_docs_site,node_docs_libs,node_playground_wasm,node_vscode_ext toneMint
class node_examples toneRose
```

## Components

### Toolchain

Language implementation, CLI entrypoints, and target emission.

- [Zero CLI](https://github.com/vercel-labs/zero/tree/main/bin/zero): user command · Primary entrypoint for check, run, build, graph, size, routes, and doctor. · `bin/zero`
- [Native compiler](https://github.com/vercel-labs/zero/tree/main/native/zero-c): C compiler · Native Zero compiler/runtime implementation and backend emission pipeline. · `native/zero-c`
- [Lex/parse](https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/lexer.c): front-end · Tokenization and syntax analysis for Zero source. · `native/zero-c/src/lexer.c`
- [Type check](https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/checker.c): semantic check · Name resolution, type checking, and language rule enforcement. · `native/zero-c/src/checker.c`
- [IR lower](https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/ir.c): middle-end · Intermediate representation used between analysis and emission. · `native/zero-c/src/ir.c`
- [Emit targets](https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/emit_wasm.c): backends · Native and WASM/object emitters plus target-specific output formats. · `native/zero-c/src/emit_wasm.c`
- [Platform IO](https://github.com/vercel-labs/zero/blob/main/native/zero-c/src/fs.c): runtime support · Filesystem and web-facing support used by the native toolchain. · `native/zero-c/src/fs.c`
- [Self-hosted compiler](https://github.com/vercel-labs/zero/tree/main/compiler-zero): Zero sources · Zero-authored compiler implementation mirroring the same pipeline. · `compiler-zero`
- [Lexer](https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/lexer.0): compiler stage · Zero-language lexer for the self-hosted compiler. · `compiler-zero/src/lexer.0`
- [Parser](https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/parser.0): compiler stage · Zero-language parser for the self-hosted compiler. · `compiler-zero/src/parser.0`
- [Checker](https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/checker.0): compiler stage · Zero-language semantic analysis and validation. · `compiler-zero/src/checker.0`
- [MIR](https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/mir.0): compiler stage · Lowered intermediate form used by the self-hosted compiler. · `compiler-zero/src/mir.0`
- [WASM emit](https://github.com/vercel-labs/zero/blob/main/compiler-zero/src/wasm.0): backend · WASM-oriented emission path in the self-hosted compiler. · `compiler-zero/src/wasm.0`
- [Package manifests](https://github.com/vercel-labs/zero/blob/main/examples/web/hello/zero.json): project model · zero.json package boundaries, targets, dependencies, and entrypoints. · `examples/web/hello/zero.json`

### Validation

Conformance suites, benchmarks, and smoke tests.

- [Conformance](https://github.com/vercel-labs/zero/tree/main/conformance): behavior contract · Pass/fail fixtures capturing parser, checker, native semantics, and packaging expectations. · `conformance`
- [Scripts](https://github.com/vercel-labs/zero/tree/main/scripts): orchestration · Benchmarks, smoke tests, contract checks, sandboxing, and reliability automation. · `scripts`
- [CLI tests](https://github.com/vercel-labs/zero/blob/main/tests/zero-cli.test.ts): external tests · TypeScript tests that validate the installed zero command from the outside. · `tests/zero-cli.test.ts`

### Experience

Documentation site and editor integration.

- [Docs site](https://github.com/vercel-labs/zero/tree/main/docs-site): web app · Documentation application with articles, routing, search, chat, playground, and OG images. · `docs-site`
- [Docs libs](https://github.com/vercel-labs/zero/blob/main/docs-site/lib/search-index.js): site logic · Search, highlighting, page metadata, GitHub integration, rate limiting, and WASM loading. · `docs-site/lib/search-index.js`
- [Playground WASM](https://github.com/vercel-labs/zero/blob/main/docs-site/public/playground/zeroc-zero.wasm): compiled artifact · Browser-ready compiler artifact embedded in the docs site. · `docs-site/public/playground/zeroc-zero.wasm`
- [VS Code ext](https://github.com/vercel-labs/zero/tree/main/extensions/vscode): editor integration · Language support for .0 files: config, syntax, snippets, and extension tests. · `extensions/vscode`

### Samples

Runnable examples and package fixtures.

- [Examples](https://github.com/vercel-labs/zero/tree/main/examples): sample suite · Curated runnable language samples across CLI, package, web, and interop scenarios. · `examples`

## Connections

- Zero CLI → Native compiler: drives · The CLI invokes the native compiler for checking, building, running, and inspection.
- Zero CLI → Package manifests: reads · Commands resolve package layout and targets from zero.json manifests.
- Native compiler → Lex/parse: starts with · Native compilation begins by lexing and parsing source text.
- Lex/parse → Type check: feeds · Parsed syntax flows into semantic validation and type checking.
- Type check → IR lower: lowers to · Checked programs are lowered into an intermediate representation.
- IR lower → Emit targets: emits · IR is turned into native, ELF, Mach-O, COFF, or WASM outputs.
- Platform IO → Native compiler: supports · Filesystem and web helpers extend runtime and toolchain capabilities.
- Self-hosted compiler → Lexer: contains · The Zero-authored compiler is organized as source modules.
- Lexer → Parser: feeds · Lexed tokens are parsed into syntax structures.
- Parser → Checker: feeds · ASTs are semantically checked and validated.
- Checker → MIR: lowers to · The self-hosted compiler lowers checked code into MIR.
- MIR → WASM emit: emits · MIR is used to generate target output, including WASM.
- Package manifests → Examples: organizes · Examples demonstrate package boundaries, entrypoints, and target declarations.
- Package manifests → Conformance: anchors · Conformance cases encode manifest and dependency behavior.
- Examples → Conformance: mirrors · Examples and fixtures overlap to exercise language and runtime behavior.
- Conformance → Native compiler: validates · Fixtures verify parser, checker, runtime, and backend behavior against the native implementation.
- Docs site → Docs libs: uses · The docs app is built from reusable site logic and data helpers.
- Docs site → Playground WASM: embeds · The browser playground runs a compiled compiler artifact.
- Docs site → Examples: documents · Articles and pages explain the example suite and language surface.
- VS Code ext → Examples: supports · The editor extension helps author the same .0 language used throughout the repo.
- Scripts → Native compiler: smokes · Automation covers native build, runtime, sanitizer, and sandbox checks.
- Scripts → Docs site: smokes · Automation includes browser and playground checks for the docs experience.
- Scripts → Conformance: runs · Scripts orchestrate conformance and contract validation workflows.
- CLI tests → Zero CLI: asserts · External tests verify the installed command interface.
