naxos-docs/docs/architecture/app-engine.md

App Engine & Workload Runtime Architecture

NaxOS features a tri-tier runtime engine that selects the best execution strategy for each application:

1. Native NixOS Systemd Services

• Best For: High-throughput services requiring direct hardware device passthrough, minimal RAM overhead, and deep integration with OpenZFS.
• Example: Immich Photo Hub.
  • Native Nixpkgs package running as an isolated systemd service.
  • Direct Intel QuickSync (/dev/dri/renderD128) access with extraPackages = [ intel-media-driver intel-compute-runtime vpl-gpu-rt ].
  • Native systemd CPU quota: CPUQuota = "200%" to avoid choking the storage daemon during intensive facial recognition or CLIP embedding indexing.
  • Photos stored directly in OpenZFS dataset /tank/media/photos.

2. Rootless Docker / Compose Engine

• Best For: General third-party containerized workloads.
• Backend: Configured with Docker's native zfs storage driver (virtualisation.docker.storageDriver = "zfs"). Container image layers become native ZFS subvolumes with instant snapshots and copy-on-write deduplication.

3. Lightweight K3s

• Best For: Cloud-native Helm charts and multi-service distributed workloads.
• Can be activated on demand via services.naxos.appEngine.k3s.enable = true.