naxos-docs/docs/architecture/overview.md

NaxOS Architecture Overview

Design Philosophy

NaxOS is an appliance-like Network Attached Storage (NAS) operating system combining the mathematical immutability of NixOS, the enterprise data integrity of OpenZFS, and the modern observability of CNCF Perses.

Traditional NAS operating systems (like TrueNAS, Unraid, or Synology DSM) rely either on mutable root filesystems with hidden configuration databases, or proprietary management stacks that can be fragile to upgrade and difficult to replicate.

NaxOS introduces an opinionated, cloud-native paradigm:

1. The Entire OS is Code: Kernel parameters, network tuning, storage datasets, shares, users, and installed applications are compiled from a single declarative definition.
2. GitOps-by-Default: Every modification made via the modern web dashboard or API is recorded as an atomic Git commit and synchronized to a remote Gitea repository.
3. True Disaster Recovery: If an update or bad configuration breaks a service, instant rollbacks return the running system to the exact previous working generation with a single command.
4. Data Safety First: Existing OpenZFS pools from legacy systems (such as nixos-lukas or TrueNAS) are imported read-safe without formatting, preserving critical application storage such as Immich photo libraries.
5. Modern Native Observability: Replaces heavy standalone Grafana instances with embedded CNCF Perses dashboards that render natively inside the web UI.

---

Architectural Subsystems

┌─────────────────────────────────────────────────────────────┐
│                   NaxOS Modern Web UI                       │
│        (React 18, Tailwind CSS, Embedded Perses)            │
└──────────────────────────────┬──────────────────────────────┘
                               │ REST / SSE / WebSockets
┌──────────────────────────────▼──────────────────────────────┐
│                  NaxOS Management Daemon                    │
│    (Node.js / TypeScript, Fastify, ZFS Driver, GitOps)       │
├──────────────────────────────┬──────────────────────────────┤
│  • Storage Controller        │  • GitOps Synchronization    │
│  • NixOS Module Generator    │  • App Engine Orchestrator   │
│  • Journald Log Streamer     │  • Perses Metrics Coordinator│
└──────────────┬───────────────┴───────────────┬──────────────┘
               │                               │
┌──────────────▼───────────────┐ ┌─────────────▼──────────────┐
│     Declarative Engine       │ │      OpenZFS Storage       │
│  /etc/naxos/repo (Git)       │ │  • zpool / zfs Primitives  │
│  nixos-rebuild-safe          │ │  • Native Encryption/Comp  │
│  System Generations          │ │  • Auto-Scrub & Snapshots  │
└──────────────┬───────────────┘ └─────────────┬──────────────┘
               │                               │
┌──────────────▼───────────────────────────────▼──────────────┐
│                    Linux / NixOS Core                       │
│  • BBR Congestion Control & 10G/25G Kernel Buffers          │
│  • Samba with Apple macOS Time Machine (vfs_fruit)          │
│  • App Runtimes: Native Systemd, Rootless Docker, K3s       │
│  • Intel QuickSync & OpenCL Hardware GPU Acceleration       │
└─────────────────────────────────────────────────────────────┘