Overview

View as Markdown

Neutron for Zig is a composable systems library with 4 opt-in layers. Each layer builds on the previous, but you can use any layer independently via compile-time build flags. It targets zero-allocation, freestanding use at the lowest layer and scales up to a full web framework with a Nucleus client.

  • Quickstart — a running HTTP server and database connection.
  • Layers — wire codecs, HAL networking, protocol servers, application framework.
  • Nucleus client — the typed client for all 14 data models.

Architecture

Layer 3: Application    ← Router, middleware, OpenAPI, config
Layer 2: Protocol       ← HTTP server, PG client, WebSocket server
Layer 1: HAL            ← TCP, I/O multiplexing, connection pool, timers
Layer 0: Wire           ← pgwire, HTTP, WebSocket, binary codecs

Build Flags

# Full stack (default)
zig build

# Wire codecs only (zero-alloc, freestanding — no std required)
zig build -Dlayer1=false -Dlayer2=false -Dlayer3=false -Dnucleus=false

# Wire + networking (no HTTP server, no framework)
zig build -Dlayer2=false -Dlayer3=false

# Everything except Nucleus client
zig build -Dnucleus=false

Minimum Zig version: 0.14.0

Project Structure

zig/
├── build.zig           # Build system with layer flags
├── build.zig.zon       # Package manifest
└── src/
    ├── wire/           # Layer 0: Codecs
    │   ├── pgwire/     # PostgreSQL protocol
    │   ├── http.zig    # HTTP/1.1
    │   ├── websocket.zig
    │   └── binary.zig
    ├── hal/            # Layer 1: Networking
    │   ├── tcp.zig
    │   ├── io.zig      # epoll/kqueue
    │   ├── pool.zig
    │   └── timer.zig
    ├── protocol/       # Layer 2: Servers
    │   ├── http_server.zig
    │   ├── pg_client.zig
    │   ├── ws_server.zig
    │   └── static.zig
    ├── app/            # Layer 3: Framework
    │   ├── app.zig
    │   ├── router.zig
    │   ├── middleware.zig
    │   ├── config.zig
    │   └── openapi.zig
    └── nucleus/        # Multi-model client
        ├── client.zig
        ├── sql.zig
        ├── kv.zig
        ├── vector.zig
        └── ...         # 15 model files