# Architecture

## Overview

zmgr is a single Rust binary that manages illumos zones via flat KDL config files under `/etc/zmgr`. No daemon, no database — just a CLI that reads configs, calls system commands (`zonecfg`, `zoneadm`, `dladm`), and writes registry entries.

## Module Layout

```
src/
  main.rs        CLI entry point (clap), command dispatch
  config.rs      Global config (/etc/zmgr/config.kdl)
  template.rs    Zone templates (/etc/zmgr/templates/*.kdl)
  pool.rs        IPAM pools (/etc/zmgr/pools/*.kdl)
  zone.rs        Zone registry (/etc/zmgr/zones/*.kdl)
  publisher.rs   IPS publishers (/etc/zmgr/publishers/*.kdl)
  exec.rs        System command wrappers (zonecfg, zoneadm, dladm)
  import.rs      Import existing zones into registry
  kdl_util.rs    KDL document parsing helpers
  error.rs       Error types (miette diagnostics)
```

## Data Flow

### Zone Creation (`zmgr create <name>`)

1. Load global config → get default template name
2. Load template → get brand, autoboot, pool reference
3. Load pool → get network, gateway, stub, IP range
4. Scan zone registry → find allocated IPs
5. Allocate next free IP from pool range
6. `dladm create-vnic` → create VNIC on stub
7. `zonecfg -z <name>` → pipe zone configuration
8. `zoneadm -z <name> install` → install zone
9. Write zone registry entry (KDL file)
10. If autoboot, `zoneadm boot`

### Zone Import (`zmgr import`)

1. `zoneadm list -cp` → get system zones
2. Filter out already-registered and bhyve zones
3. `zonecfg -z <name> info` → extract config
4. Match brand → template, IP → pool
5. Write zone registry entry

## Dependency Graph

```
main.rs
  ├── config.rs     ← kdl_util.rs, error.rs
  ├── template.rs   ← kdl_util.rs, error.rs
  ├── pool.rs       ← kdl_util.rs, error.rs, zone.rs
  ├── zone.rs       ← kdl_util.rs, error.rs
  ├── publisher.rs  ← kdl_util.rs, error.rs
  ├── exec.rs       ← error.rs
  └── import.rs     ← exec.rs, pool.rs, template.rs, zone.rs
```

## Boundary with vm-manager

zmgr manages **zone brands** (ipkg, nlipkg, etc.) — native illumos zones.
vm-manager manages **bhyve** brand zones — virtual machines.
Import logic skips bhyve zones to avoid overlap.