# Overview

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](/docs/zig/quickstart) — a running HTTP server and database connection.
- [Layers](/docs/zig/layers) — wire codecs, HAL networking, protocol servers, application framework.
- [Nucleus client](/docs/zig/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

```bash
# 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
```