# vercel-labs/zero-native architecture

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

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

## Overview

1. **Repository shape**
   - This is a monorepo for a Zig-based desktop app framework plus its CLI, docs, examples, and publishable npm wrapper.
   - The core product lives in `src/`; `examples/` shows consumer apps; `docs/` is a separate Next.js documentation site; `packages/zero-native` is the JavaScript package used for installation/distribution.

2. **Core runtime model**
   - The central abstraction is an `App` described in Zig and a `Runtime` that owns the event loop, windows, bridge dispatch, automation hooks, tracing, and platform services.
   - The root Zig exports are organized from `src/root.zig`, with feature areas split into modules like `frontend`, `bridge`, `embed`, `extensions`, `automation`, `security`, and `runtime`.

3. **Platform boundary**
   - `src/platform/` is the OS abstraction layer, with separate implementations for macOS, Linux, and Windows.
   - Each platform subfolder contains native host code for embedding the web engine: AppKit/Objective-C++ on macOS, GTK/C/C++ on Linux, and WebView2/CEF C++ host code on Windows.
   - This is the main boundary between portable Zig logic and OS-specific UI/runtime integration.

4. **Web engine integration**
   - zero-native supports two execution modes: the platform’s system WebView or bundled Chromium via CEF.
   - The engine choice is part of app configuration and determines whether the runtime delegates to native WebKit/WebView2/WebKitGTK or to a bundled CEF runtime.
   - `third_party/cef` and `tools/cef` support vendoring/building the Chromium runtime when needed.

5. **Frontend delivery**
   - The frontend is treated as web content loaded by the native shell, not as the application host itself.
   - `src/frontend/` and `src/embed/` cover how packaged assets, inline HTML, URLs, or local dev servers are exposed to the runtime.
   - Example apps show common frontends built with Next.js, React/Vite, Svelte/Vite, and Vue/Vite.

6. **JavaScript-to-native bridge**
   - `window.zero.invoke()` is the primary JS-to-Zig call path.
   - Bridge calls are routed through `src/bridge/`, with checks for origin, permissions, size limits, and registered handler availability.
   - The bridge is a deliberate security boundary: web content is not trusted by default, and native capabilities must be explicitly enabled.

7. **Security and policy**
   - Security policy is a first-class part of the app manifest and runtime behavior.
   - `src/security/`, plus platform policy logic, govern navigation allowlists, external link handling, permissions, and window capabilities.
   - This architecture keeps web content, native commands, and OS integrations separated unless explicitly authorized.

8. **Manifest-driven configuration**
   - `app.zon` is the primary app manifest and defines metadata, icons, window layout, frontend source, web engine selection, security settings, bridge permissions, and packaging inputs.
   - The `src/primitives/app_manifest` and `src/tooling/manifest` modules indicate the manifest is parsed and validated as part of the build/tooling pipeline, not ad hoc at runtime.

9. **Tooling and developer workflow**
   - `src/tooling/` provides the CLI-facing functionality: app initialization, dev mode, doctor checks, packaging, code signing, assets, templates, web engine handling, and manifest processing.
   - `tools/zero-native/` contains the CLI entry point, while `packages/zero-native` wraps distribution for npm and handles binary/framework copy and version sync scripts.
   - This means the repo is both a library/runtime and a bootstrap/distribution system.

10. **Automation and debugging**
    - `src/automation/` is a distinct subsystem for app automation, snapshotting, and protocol/server support.
    - `src/debug/` and `src/primitives/diagnostics` support diagnostics and troubleshooting, which are also surfaced through tooling commands like doctor.
    - These pieces sit alongside the runtime rather than inside the app UI path.

11. **Shared primitives**
    - `src/primitives/` contains reusable low-level building blocks: geometry, JSON, assets, platform info, app directories, trace, diagnostics, and manifest helpers.
    - These modules are shared across runtime, tooling, and platform code, reducing duplication in the higher-level subsystems.

12. **Native embedding examples**
    - `examples/ios` and `examples/android` show mobile hosts embedding the zero-native C ABI from a native app, rather than launching the standard desktop runtime.
    - `examples/webview` shows a minimal native shell, while the framework examples demonstrate the desktop pattern of `app.zon` + Zig shell + frontend project.
    - This indicates the library can be used both as a desktop app shell and as an embeddable native component.

13. **Documentation and release pipeline**
    - `docs/` is a standalone Next.js documentation site with MDX content, search indexing, and generated page metadata.
    - GitHub Actions workflows cover CI and release, plus CEF runtime packaging, which matters because the bundled Chromium path is a separate artifact from the system-WebView path.

14. **Build and packaging model**
    - `build.zig` and `build.zig.zon` drive the native build, while frontend examples use their own package managers/build tools.
    - Packaging includes icons, entitlements, signing, and runtime assets, reflecting that the final deliverable is a native app bundle with embedded web content or a linked browser runtime.

Main entry points: [`src/root.zig`](https://github.com/vercel-labs/zero-native/blob/main/src/root.zig) (src/root.zig), [`src/runtime/root.zig`](https://github.com/vercel-labs/zero-native/blob/main/src/runtime/root.zig) (Runtime), [`src/platform/root.zig`](https://github.com/vercel-labs/zero-native/blob/main/src/platform/root.zig) (Platform layer), [`src/tooling/root.zig`](https://github.com/vercel-labs/zero-native/blob/main/src/tooling/root.zig) (Tooling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_src_root["src/root.zig<br/>entrypoint<br/>[root.zig]"]
  node_runtime["Runtime<br/>event loop<br/>[root.zig]"]
  node_bridge["Bridge<br/>JS-native IPC<br/>[root.zig]"]
  node_frontend["Frontend<br/>content loading<br/>[root.zig]"]
  node_embed["Embed<br/>shell integration<br/>[root.zig]"]
  node_security["Security<br/>policy<br/>[root.zig]"]
  node_automation["Automation<br/>[root.zig]"]
  node_primitives["Primitives<br/>shared libs"]
end

subgraph group_platform["Platform hosts"]
  node_platform_root["Platform layer<br/>OS abstraction<br/>[root.zig]"]
  node_macos["macOS host<br/>native host<br/>[root.zig]"]
  node_linux["Linux host<br/>native host<br/>[root.zig]"]
  node_windows["Windows host<br/>native host<br/>[root.zig]"]
end

subgraph group_tooling["Tooling & packaging"]
  node_tooling_root["Tooling<br/>CLI subsystems<br/>[root.zig]"]
  node_cli["CLI entry<br/>command runner<br/>[main.zig]"]
end

subgraph group_docs["Docs site"]
  node_docs_site["Docs site<br/>nextjs app<br/>[page.mdx]"]
end

subgraph group_examples["Examples"]
  node_examples_suite["Examples<br/>sample apps<br/>[README.md]"]
end

subgraph group_distribution["Distribution"]
  node_npm_pkg["zero-native pkg<br/>npm wrapper<br/>[package.json]"]
end

node_repo["zero-native<br/>monorepo"]

node_repo -->|"core library"| node_src_root
node_repo -->|"CLI/tooling"| node_tooling_root
node_repo -->|"docs"| node_docs_site
node_repo -->|"samples"| node_examples_suite
node_repo -->|"distribution"| node_npm_pkg
node_src_root -->|"exports"| node_runtime
node_src_root -->|"exports"| node_bridge
node_src_root -->|"exports"| node_frontend
node_src_root -->|"exports"| node_embed
node_src_root -->|"exports"| node_security
node_src_root -->|"exports"| node_automation
node_src_root -->|"shared core"| node_primitives
node_runtime -->|"host services"| node_platform_root
node_runtime -->|"dispatches"| node_bridge
node_runtime -->|"loads"| node_frontend
node_runtime -->|"enforces"| node_security
node_runtime -->|"supports"| node_automation
node_tooling_root -->|"drives"| node_cli
node_tooling_root -->|"packages"| node_npm_pkg
node_tooling_root -->|"parses config"| node_primitives
node_platform_root -->|"selects"| node_macos
node_platform_root -->|"selects"| node_linux
node_platform_root -->|"selects"| node_windows
node_platform_root -->|"policy hooks"| node_security
node_docs_site -.->|"documents"| node_src_root
node_examples_suite -.->|"consumes"| node_src_root
node_npm_pkg -->|"installs"| node_cli
node_npm_pkg -.->|"syncs versions"| node_tooling_root

click node_src_root "https://github.com/vercel-labs/zero-native/blob/main/src/root.zig"
click node_runtime "https://github.com/vercel-labs/zero-native/blob/main/src/runtime/root.zig"
click node_bridge "https://github.com/vercel-labs/zero-native/blob/main/src/bridge/root.zig"
click node_frontend "https://github.com/vercel-labs/zero-native/blob/main/src/frontend/root.zig"
click node_embed "https://github.com/vercel-labs/zero-native/blob/main/src/embed/root.zig"
click node_security "https://github.com/vercel-labs/zero-native/blob/main/src/security/root.zig"
click node_automation "https://github.com/vercel-labs/zero-native/blob/main/src/automation/root.zig"
click node_primitives "https://github.com/vercel-labs/zero-native/tree/main/src/primitives"
click node_platform_root "https://github.com/vercel-labs/zero-native/blob/main/src/platform/root.zig"
click node_macos "https://github.com/vercel-labs/zero-native/blob/main/src/platform/macos/root.zig"
click node_linux "https://github.com/vercel-labs/zero-native/blob/main/src/platform/linux/root.zig"
click node_windows "https://github.com/vercel-labs/zero-native/blob/main/src/platform/windows/root.zig"
click node_tooling_root "https://github.com/vercel-labs/zero-native/blob/main/src/tooling/root.zig"
click node_cli "https://github.com/vercel-labs/zero-native/blob/main/tools/zero-native/main.zig"
click node_npm_pkg "https://github.com/vercel-labs/zero-native/blob/main/packages/zero-native/package.json"
click node_docs_site "https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/page.mdx"
click node_examples_suite "https://github.com/vercel-labs/zero-native/blob/main/examples/README.md"

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_src_root,node_runtime,node_bridge,node_frontend,node_embed,node_security,node_automation,node_primitives toneBlue
class node_platform_root,node_macos,node_linux,node_windows toneAmber
class node_tooling_root,node_cli toneMint
class node_docs_site toneRose
class node_examples_suite toneIndigo
class node_npm_pkg toneTeal
class node_repo toneNeutral
```

## Components

### Core runtime

Zig app/runtime, bridge, security, embedding, and shared primitives.

- [src/root.zig](https://github.com/vercel-labs/zero-native/blob/main/src/root.zig): entrypoint · Top-level Zig exports wiring the library subsystems together. · `src/root.zig`
- [Runtime](https://github.com/vercel-labs/zero-native/blob/main/src/runtime/root.zig): event loop · Owns windows, bridge dispatch, automation hooks, tracing, and platform services. · `src/runtime/root.zig`
- [Bridge](https://github.com/vercel-labs/zero-native/blob/main/src/bridge/root.zig): JS-native IPC · window.zero.invoke() call path with origin, permission, and handler checks. · `src/bridge/root.zig`
- [Frontend](https://github.com/vercel-labs/zero-native/blob/main/src/frontend/root.zig): content loading · Loads packaged assets, inline HTML, URLs, and local dev server content. · `src/frontend/root.zig`
- [Embed](https://github.com/vercel-labs/zero-native/blob/main/src/embed/root.zig): shell integration · Connects frontend delivery to the native shell and runtime embedding model. · `src/embed/root.zig`
- [Security](https://github.com/vercel-labs/zero-native/blob/main/src/security/root.zig): policy · Navigation, permissions, external links, and window capability policy. · `src/security/root.zig`
- [Automation](https://github.com/vercel-labs/zero-native/blob/main/src/automation/root.zig): automation · App automation, snapshotting, and protocol/server support. · `src/automation/root.zig`
- [Primitives](https://github.com/vercel-labs/zero-native/tree/main/src/primitives): shared libs · Reusable low-level helpers for manifest, assets, diagnostics, geometry, JSON, trace, and platform info. · `src/primitives`

### Platform hosts

OS-specific native embedding layers for desktop and mobile integrations.

- [Platform layer](https://github.com/vercel-labs/zero-native/blob/main/src/platform/root.zig): OS abstraction · Portable boundary that selects native host implementations per OS. · `src/platform/root.zig`
- [macOS host](https://github.com/vercel-labs/zero-native/blob/main/src/platform/macos/root.zig): native host · AppKit/Objective-C++ embedding and macOS-specific automation and CEF host code. · `src/platform/macos/root.zig`
- [Linux host](https://github.com/vercel-labs/zero-native/blob/main/src/platform/linux/root.zig): native host · GTK/C/C++ embedding plus Linux CEF host code. · `src/platform/linux/root.zig`
- [Windows host](https://github.com/vercel-labs/zero-native/blob/main/src/platform/windows/root.zig): native host · WebView2 and CEF host integration for Windows. · `src/platform/windows/root.zig`

### Tooling & packaging

CLI, manifest processing, packaging, and distribution helpers.

- [Tooling](https://github.com/vercel-labs/zero-native/blob/main/src/tooling/root.zig): CLI subsystems · Dev, doctor, packaging, signing, templates, manifest, and web engine workflows. · `src/tooling/root.zig`
- [CLI entry](https://github.com/vercel-labs/zero-native/blob/main/tools/zero-native/main.zig): command runner · zero-native command entry point and automation-facing CLI glue. · `tools/zero-native/main.zig`

### Docs site

Standalone Next.js documentation app and content.

- [Docs site](https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/page.mdx): nextjs app · Standalone Next.js documentation site with MDX content and search. · `docs/src/app/page.mdx`

### Examples

Reference consumer apps and embedding samples.

- [Examples](https://github.com/vercel-labs/zero-native/blob/main/examples/README.md): sample apps · Desktop, webview, iOS, Android, and frontend framework examples. · `examples/README.md`

### Distribution

Publishable npm wrapper and native binary installation scripts.

- [zero-native pkg](https://github.com/vercel-labs/zero-native/blob/main/packages/zero-native/package.json): npm wrapper · Distribution package that installs binaries/frameworks and synchronizes versions. · `packages/zero-native/package.json`

### Other components

- **zero-native**: monorepo · Zig desktop app framework, CLI, docs, examples, and npm distribution wrapper.

## Connections

- zero-native → src/root.zig: core library · Top-level repository contains the Zig library runtime.
- zero-native → Tooling: CLI/tooling · Repository includes build, dev, packaging, and doctor workflows.
- zero-native → Docs site: docs · Repository includes a standalone documentation application.
- zero-native → Examples: samples · Repository includes consumer and embedding examples.
- zero-native → zero-native pkg: distribution · Repository publishes a Node package wrapper.
- src/root.zig → Runtime: exports · Root Zig exports the runtime subsystem.
- src/root.zig → Bridge: exports · Root Zig exports the bridge subsystem.
- src/root.zig → Frontend: exports · Root Zig exports frontend loading helpers.
- src/root.zig → Embed: exports · Root Zig exports embedding helpers.
- src/root.zig → Security: exports · Root Zig exports policy and security helpers.
- src/root.zig → Automation: exports · Root Zig exports automation features.
- src/root.zig → Primitives: shared core · Root Zig depends on shared primitives.
- Runtime → Platform layer: host services · Runtime delegates OS services through platform abstraction.
- Runtime → Bridge: dispatches · Runtime routes native calls through the bridge.
- Runtime → Frontend: loads · Runtime presents app frontend content.
- Runtime → Security: enforces · Runtime applies security policy during navigation and capability use.
- Runtime → Automation: supports · Runtime exposes automation and snapshot support.
- Tooling → CLI entry: drives · Tooling powers the command-line entry point.
- Tooling → zero-native pkg: packages · Tooling feeds distribution and install scripts.
- Tooling → Primitives: parses config · Tooling uses shared manifest and diagnostics helpers.
- Platform layer → macOS host: selects · Portable platform layer selects macOS host implementation.
- Platform layer → Linux host: selects · Portable platform layer selects Linux host implementation.
- Platform layer → Windows host: selects · Portable platform layer selects Windows host implementation.
- Platform layer → Security: policy hooks · Platform layer contributes navigation and capability policy enforcement.
- Docs site → src/root.zig: documents · Docs explain the library and runtime architecture.
- Examples → src/root.zig: consumes · Examples demonstrate the library runtime and embedding APIs.
- zero-native pkg → CLI entry: installs · Package wrapper installs the native CLI binary.
- zero-native pkg → Tooling: syncs versions · Distribution scripts align package and binary versions.