# Zinit - Overview & Workspace Structure
## Problem Statement
Current zinit has fundamental issues:
- Race conditions in async state management
- Broken dependency ordering (`after` not honored)
- State detection issues (services shown blocked while running)
- No visibility into why services are blocked
## Goals
- Explicit state machine (all states and transitions defined, testable)
- Validate before mutate (graph changes validated on copy, then swapped)
- Hybrid concurrency (locks for request/response, channels for async events)
- Visibility (always know *why* something is blocked or failed)
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ zinit-pid1 │
│ - Spawns/monitors zinit-server │
│ - Forwards signals (SIGTERM→shutdown, SIGUSR1→soft restart) │
│ - Reaps orphan zombies │
│ - Never exits on VM/bare-metal (reboot syscall) │
└─────────────────────────────────────────────────────────────────┘
│
│ spawns / signals
▼
┌─────────────────────────────────────────────────────────────────┐
│ zinit-server │
│ - Service lifecycle (start, stop, restart) │
│ - Dependency graph with ordering and requirements │
│ - State machine per service │
│ - Log capture and optional forwarding │
│ - Unix socket RPC (JSON-RPC 2.0) │
└─────────────────────────────────────────────────────────────────┘
│
│ unix socket
▼
┌─────────────────────────────────────────────────────────────────┐
│ zinit-client │
│ (CLI / TUI / Rhai) │
└─────────────────────────────────────────────────────────────────┘
```
## Workspace Layout
```
zinit/
├── Cargo.toml # Workspace definition
├── zinit-common/ # Shared types and blocking client
├── zinit-server/ # Service supervisor
├── zinit-client/ # CLI/TUI
└── zinit-pid1/ # Init shim
```
## Dependency Graph (Crates)
```
zinit-common (serde, serde_json only)
↑
├── zinit-server (+ tokio, petgraph, nix, thiserror, tracing)
├── zinit-client (+ clap, optional: ratatui, tokio)
└── zinit-pid1 (+ nix, tracing)
```
## Workspace Cargo.toml
```toml
[workspace]
resolver = "2"
members = [
"zinit-common",
"zinit-server",
"zinit-client",
"zinit-pid1",
]
[workspace.package]
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"
[workspace.dependencies]
# Shared
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
# Async
tokio = { version = "1", features = ["full", "process"] }
# Graph
petgraph = "0.6"
# Unix
nix = { version = "0.27", features = ["signal", "process"] }
libc = "0.2"
# Error handling
thiserror = "1"
# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
# CLI
clap = { version = "4", features = ["derive"] }
```
## Socket Paths
- System: `/var/run/zinit.sock`
- User: `~/hero/var/zinit.sock`
## Config Paths
- System: `/etc/zinit/services/` and `/etc/zinit/targets/`
- User: `~/hero/var/zinit/services/`
## State Symbols (ASCII)
```
[-] = inactive
[?] = blocked
[>] = starting
[+] = running
[!] = stopping
[.] = exited
[X] = failed
```
## Related Spec Documents
- `01-zinit-common.md` - Shared crate (types, protocol, client)
- `02-state-machine.md` - Service state machine
- `03-dependency-graph.md` - Graph structure and queries
- `04-process-log.md` - Process and log management
- `05-supervisor.md` - Supervisor and IPC
- `06-zinit-pid1.md` - PID 1 specification
- `07-implementation.md` - Implementation order