Update CLAUDE.md to reflect current distributed architecture

Add documentation for mvirt-api (Raft control plane), mvirt-node (reconciliation agent),
mvirt-ebpf (eBPF networking), mvirt-ui (web dashboard), and NixOS build system.
Consolidate gRPC services table and streamline logging examples.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: MalteJ

CLAUDE.md

@@ -6,16 +6,47 @@ See [README.md](README.md) for build commands and project overview.
 
 ```
 mvirt/
-├── mvirt-cli/       # CLI client + TUI
-├── mvirt-vmm/       # Daemon (VM Manager)
-├── mvirt-log/       # Centralized logging service
-├── mvirt-zfs/       # ZFS storage management
-├── mvirt-one/       # MicroVM Init System for isolated Pods
-│   ├── src/         # Rust init process (PID 1)
-│   ├── proto/       # one gRPC API
+├── mvirt-api/       # Raft-based distributed control plane
+│   ├── src/
+│   │   ├── grpc/    # gRPC NodeService server
+│   │   ├── rest/    # REST API (handlers per resource)
+│   │   ├── store/   # Raft storage, event sourcing
+│   │   ├── state.rs # State machine + command handling
+│   │   └── scheduler.rs
+│   └── proto/       # node.proto
+├── mvirt-node/      # Node agent (reconciles desired state from API)
+│   ├── src/
+│   │   ├── clients/ # gRPC clients for local services (vmm, ebpf, zfs)
+│   │   └── reconciler/ # Per-resource reconcilers (vm, nic, volume, network, route, security_group, template)
+├── mvirt-vmm/       # Local hypervisor daemon (VM + Pod management)
+│   ├── src/
+│   │   ├── grpc.rs        # VmService implementation
+│   │   ├── hypervisor.rs  # cloud-hypervisor process management
+│   │   ├── pod_service.rs # PodService implementation
+│   │   └── store.rs       # SQLite state
+│   └── proto/       # mvirt.proto (VmService + PodService)
+├── mvirt-ebpf/      # eBPF-based networking (replaces mvirt-net)
+│   ├── src/
+│   │   ├── ebpf_loader.rs   # eBPF program loading
+│   │   ├── proto_handler.rs # IPv4/IPv6/DHCP/ICMP handling
+│   │   ├── tap.rs           # TAP device management
+│   │   └── nat.rs           # NAT + conntrack
+│   └── programs/    # eBPF kernel-space programs
+├── mvirt-zfs/       # ZFS storage daemon
+│   └── proto/       # zfs.proto
+├── mvirt-log/       # Centralized audit logging service
+│   └── proto/       # log.proto
+├── mvirt-one/       # MicroVM Init System (PID 1 for Pods)
+│   ├── src/
+│   ├── proto/       # one.proto
 │   └── initramfs/   # rootfs skeleton
-├── proto/           # gRPC API definition
-└── images/          # Kernel and disk images (not in git)
+├── mvirt-cli/       # CLI client + TUI (ratatui)
+├── mvirt-ui/        # Web UI (React + Vite + Tailwind)
+├── nix/             # NixOS modules, packages, images
+│   ├── modules/     # mvirt.nix (service definitions)
+│   ├── packages/    # Build derivations
+│   └── images/      # hypervisor.nix, node.nix
+└── proto/           # Legacy shared proto (per-crate protos preferred)
 ```
 
 ## Code Quality
@@ -29,143 +60,119 @@ No warnings allowed.
 
 ## Architecture
 
-### gRPC API (proto/mvirt.proto)
-- `CreateVm`, `GetVm`, `ListVms`, `DeleteVm` - CRUD
-- `StartVm`, `StopVm`, `KillVm` - Lifecycle
-- `Console` - Bidirectional streaming for serial console
+### Distributed Control Plane (mvirt-api)
 
-### SQLite Schema (store.rs)
-- `vms` table: VM definitions (id, name, state, config_json, timestamps)
-- `vm_runtime` table: Runtime info for running VMs (pid, sockets)
+Raft-based consensus for multi-node cluster management.
+
+- **Raft** via `mraft` for leader election and log replication
+- **REST API** on port 8080 for external clients and UI
+- **gRPC NodeService** on port 50056 for node agents
+- **Raft** inter-node communication on port 6001
+- **Event-sourced state machine** (`state.rs`) processes all commands
+- **Scheduler** assigns resources to nodes
+
+REST handlers are split per resource: `controlplane.rs`, `nodes.rs`, `vms.rs`, `networks.rs`, `nics.rs`.
+
+### Node Agent (mvirt-node)
+
+Runs on each hypervisor node, connects to mvirt-api.
+
+- Registers with the API, sends heartbeats
+- Watches spec stream (`WatchSpecs`) for desired state
+- Reconciles locally via per-resource reconcilers (VM, NIC, volume, network, route, security group, template)
+- Reports status back via `UpdateResourceStatus`
+
+### Local Hypervisor (mvirt-vmm)
+
+gRPC services: **VmService** + **PodService** on port 50051.
 
-### Hypervisor (hypervisor.rs)
 - Spawns cloud-hypervisor processes
 - Creates TAP devices and attaches to bridge
 - Generates cloud-init ISO
 - Background watcher monitors child processes
 - `recover_vms()` on daemon startup cleans up stale VMs
+- Pod lifecycle via vsock communication with mvirt-one
+
+### eBPF Networking (mvirt-ebpf)
 
-### TUI (tui.rs)
-- Non-blocking async with channels
-- Background worker handles gRPC calls
-- Auto-refresh every 2 seconds
+Replaces legacy mvirt-net. In-kernel packet processing via eBPF.
+
+- IPv4/IPv6 routing, DHCP, ICMP handling
+- NAT and connection tracking
+- TAP device management
+- Security groups
+
+### ZFS Storage (mvirt-zfs)
+
+gRPC **ZfsService** for volume management.
+
+- Volume CRUD and resize
+- Snapshot management
+- Template import with progress tracking (HTTP/file)
+- Clone from templates
 
 ### Event Logging (mvirt-log)
 
-Centralized audit log for all mvirt components. Logs are stored in SQLite with many-to-many object relations.
+Centralized audit log. SQLite with many-to-many object relations.
 
 **Schema:**
 ```sql
 logs (id INTEGER PRIMARY KEY, timestamp_ns, message, level, component)
-log_objects (log_id, object_id)  -- junction table for many-to-many
-```
-
-**Proto API** (`mvirt-log/proto/log.proto`):
-```protobuf
-service LogService {
-  rpc Log(LogRequest) returns (LogResponse);      // append log
-  rpc Query(QueryRequest) returns (stream LogEntry);  // query logs
-}
-
-message LogEntry {
-  string id = 1;
-  int64 timestamp_ns = 2;
-  string message = 3;
-  LogLevel level = 4;           // INFO, WARN, ERROR, DEBUG, AUDIT
-  string component = 5;         // "vmm", "zfs", "cli"
-  repeated string related_object_ids = 6;  // ["vm-123", "vol-456"]
-}
-```
-
-**Dependency** (in component's Cargo.toml):
-```toml
-mvirt-log = { path = "../mvirt-log" }
+log_objects (log_id, object_id)  -- junction table
 ```
 
-**Logging from components:**
+**AuditLogger Usage** (recommended):
 ```rust
-use mvirt_log::{LogServiceClient, LogEntry, LogLevel, LogRequest};
-
-// Connect to mvirt-log
-let mut client = LogServiceClient::connect("http://[::1]:50052").await?;
-
-// Log an event with related objects
-client.log(LogRequest {
-    entry: Some(LogEntry {
-        message: "VM started".into(),
-        level: LogLevel::Info as i32,
-        component: "vmm".into(),
-        related_object_ids: vec![vm_id.clone()],
-        ..Default::default()  // id and timestamp auto-generated
-    }),
-}).await?;
-
-// Log event related to multiple objects (e.g., disk attached to VM)
-client.log(LogRequest {
-    entry: Some(LogEntry {
-        message: "Volume attached".into(),
-        level: LogLevel::Audit as i32,
-        component: "zfs".into(),
-        related_object_ids: vec![vm_id, volume_id],  // indexed under both
-        ..Default::default()
-    }),
-}).await?;
+use mvirt_log::{AuditLogger, LogLevel, create_audit_logger};
+
+let audit = create_audit_logger("http://[::1]:50052", "vmm");
+audit.log(LogLevel::Audit, "VM created", vec![vm_id]).await;
 ```
 
-**Querying logs:**
-```rust
-use mvirt_log::{LogServiceClient, QueryRequest};
+### MicroVM Init (mvirt-one)
 
-let mut stream = client.query(QueryRequest {
-    object_id: Some("vm-123".into()),
-    limit: 100,
-    ..Default::default()
-}).await?.into_inner();
+PID 1 init process running inside MicroVMs for container pods. Provides OneService gRPC for container lifecycle, log streaming, exec sessions.
 
-while let Some(entry) = stream.message().await? {
-    println!("{}: {}", entry.timestamp_ns, entry.message);
-}
-```
+### TUI (mvirt-cli)
 
-### Log-Level Guidelines
+ratatui-based terminal UI with non-blocking async and background gRPC workers.
 
-| Level | Verwendung | Beispiele |
-|-------|------------|-----------|
-| **AUDIT** | Alle State-ändernden Operationen (CRUD + Lifecycle) | VM/Volume/NIC created/deleted/started/stopped/killed |
-| **INFO** | Informative Events ohne State-Änderung | Service gestartet, Connection hergestellt |
-| **WARN** | Degraded Operations, Retries | Connection retry, Fallback aktiviert |
-| **ERROR** | Fehlgeschlagene Operationen | VM start failed, Import failed |
-| **DEBUG** | Entwickler-Diagnostik | Detaillierte Trace-Infos |
+### Web UI (mvirt-ui)
 
-**AuditLogger Usage** (empfohlen statt direktem Client):
-```rust
-use mvirt_log::{AuditLogger, LogLevel, create_audit_logger};
+React + Vite + Tailwind dashboard. Communicates with mvirt-api REST API on port 8080.
 
-// In main.rs: Create shared audit logger
-let audit = create_audit_logger("http://[::1]:50052", "vmm");
+## gRPC Services
 
-// Automatisch: Dual-Logging (lokal via tracing + remote via mvirt-log)
-audit.log(LogLevel::Audit, "VM created", vec![vm_id]).await;
-```
+| Proto | Service | Port | Key RPCs |
+|-------|---------|------|----------|
+| `mvirt-api/proto/node.proto` | NodeService | 50056 | Register, Heartbeat, Deregister, WatchSpecs, UpdateResourceStatus |
+| `mvirt-vmm/proto/mvirt.proto` | VmService, PodService | 50051 | CreateVm, StartVm, StopVm, Console, PodLogs, PodExec |
+| `mvirt-one/proto/one.proto` | OneService | (vsock) | CreatePod, StartPod, StopPod, Logs, Exec |
+| `mvirt-zfs/proto/zfs.proto` | ZfsService | 50053 | CreateVolume, ImportTemplate, CreateSnapshot, CloneFromTemplate |
+| `mvirt-log/proto/log.proto` | LogService | 50052 | Log, Query |
 
-**Component-specific wrappers** (in `mvirt-zfs`, `mvirt-net`):
-```rust
-// ZfsAuditLogger wraps AuditLogger with domain-specific methods
-use crate::audit::{create_audit_logger, ZfsAuditLogger};
+## Log-Level Guidelines
 
-let audit = create_audit_logger(&args.log_endpoint);
-audit.volume_created(&volume_id, &volume_name, size).await;
-```
+| Level | Usage | Examples |
+|-------|-------|---------|
+| **AUDIT** | State-changing operations (CRUD + Lifecycle) | VM/Volume/NIC created/deleted/started/stopped |
+| **INFO** | Informational events without state change | Service started, connection established |
+| **WARN** | Degraded operations, retries | Connection retry, fallback activated |
+| **ERROR** | Failed operations | VM start failed, import failed |
+| **DEBUG** | Developer diagnostics | Detailed trace info |
 
 ## Key Decisions
 
-- **SQLite** for persistence (not in-memory)
+- **Raft consensus** for distributed cluster state (mraft)
+- **Event sourcing** in mvirt-api state machine
+- **Reconciliation loop** pattern (desired state vs actual state)
+- **SQLite** for local persistence
 - **cloud-hypervisor** instead of QEMU
-- **TAP + bridge** networking
-- **Async channels** in TUI
-- **Console escape**: Ctrl+a t
+- **eBPF** for in-kernel networking (replaces bridge-based mvirt-net)
 - **musl** for static linking
 - **Direct kernel boot** for MicroVMs
+- **NixOS** for reproducible builds and deployment (flake.nix + crane)
+- **Console escape**: Ctrl+a t
 
 ## Common Issues
 

mvirt-api/src/grpc/server.rs

@@ -80,14 +80,23 @@ impl NodeServiceImpl {
         *rev
     }
 
-    /// Send a spec event to a specific node.
+    /// Send a spec event to a specific node (by ID or name).
     pub async fn send_spec_to_node(&self, node_id: &str, event: SpecEvent) -> Result<(), Status> {
         let senders = self.spec_senders.read().await;
+        // Try direct ID lookup first
         if let Some(sender) = senders.get(node_id) {
             sender.send(Ok(event)).await.map_err(|_| {
                 Status::internal(format!("Failed to send spec to node {}", node_id))
             })?;
+            return Ok(());
         }
+        // Try resolving name to ID
+        if let Ok(Some(node)) = self.store.get_node_by_name(node_id).await
+            && let Some(sender) = senders.get(&node.id) {
+                sender.send(Ok(event)).await.map_err(|_| {
+                    Status::internal(format!("Failed to send spec to node {}", node_id))
+                })?;
+            }
         Ok(())
     }
 
@@ -124,7 +133,7 @@ impl NodeServiceImpl {
         use super::proto::{
             NetworkSpec as ProtoNetworkSpec, NicSpec as ProtoNicSpec, ResourceMeta, SpecEvent,
             SpecEventType, VmDesiredState as ProtoVmDesiredState, VmSpec as ProtoVmSpec,
-            spec_event,
+            VolumeSpec as ProtoVolumeSpec, spec_event,
         };
 
         let revision = self.next_revision().await;
@@ -276,6 +285,52 @@ impl NodeServiceImpl {
                 self.broadcast_spec(spec_event).await;
             }
 
+            // Volume created - send to specific node
+            Event::VolumeCreated(volume) => {
+                let spec_event = SpecEvent {
+                    revision,
+                    r#type: SpecEventType::Create as i32,
+                    spec: Some(spec_event::Spec::Volume(ProtoVolumeSpec {
+                        meta: Some(ResourceMeta {
+                            id: volume.id.clone(),
+                            name: volume.name.clone(),
+                            project_id: volume.project_id.clone(),
+                            node_id: Some(volume.node_id.clone()),
+                            ..Default::default()
+                        }),
+                        size_gb: volume.size_bytes / (1024 * 1024 * 1024),
+                        template_id: volume.template_id.clone(),
+                        attached_vm_id: None,
+                    })),
+                };
+
+                tracing::info!(
+                    "Sending volume spec {} to node {}",
+                    volume.id,
+                    volume.node_id
+                );
+                self.send_spec_to_node(&volume.node_id, spec_event).await?;
+            }
+
+            // Volume deleted - send to specific node
+            Event::VolumeDeleted { id, node_id } => {
+                let spec_event = SpecEvent {
+                    revision,
+                    r#type: SpecEventType::Delete as i32,
+                    spec: Some(spec_event::Spec::Volume(ProtoVolumeSpec {
+                        meta: Some(ResourceMeta {
+                            id: id.clone(),
+                            node_id: Some(node_id.clone()),
+                            ..Default::default()
+                        }),
+                        ..Default::default()
+                    })),
+                };
+
+                tracing::info!("Sending volume delete {} to node {}", id, node_id);
+                self.send_spec_to_node(&node_id, spec_event).await?;
+            }
+
             // Other events don't require spec distribution
             _ => {}
         }

mvirt-api/src/main.rs

@@ -164,6 +164,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     info!("Waiting for leader election...");
     if let Some(leader) = node.wait_for_leader(Duration::from_secs(10)).await {
         info!("Leader elected: node {}", leader);
+        // Set is_leader flag so state machine emits events via broadcast channel
+        if leader == node_id {
+            let flag = node.is_leader_flag();
+            flag.store(true, std::sync::atomic::Ordering::SeqCst);
+        }
     } else {
         warn!("No leader elected within timeout");
     }