naxos-docs/docs/architecture/declarative-backend.md

Declarative Backend & GitOps Synchronization Engine

Core Workflow

NaxOS eliminates drift between what the Web Dashboard displays and what the underlying operating system executes.

When an administrator performs an action in the UI (e.g. creating a share, setting a dataset quota, installing Immich):

1. REST API Request: The frontend sends a strongly typed JSON payload to the NaxOS Management Daemon (naxos-api).
2. In-Memory & JSON State Update: The daemon validates the payload against its schemas and updates /etc/naxos/repo/naxos-config.json.
3. NixOS Code Generation: The daemon's compiler generates /etc/naxos/repo/generated-naxos-config.nix.
4. Git Transaction:
   • The daemon commits the modified files into the local Git repository at /etc/naxos/repo.
   • If a remote repository is configured (e.g. on Gitea), it pushes the commit automatically to origin/main.
5. Dry-Run Validation:
   • Before any running service is altered, naxos-rebuild-safe performs a dry build:

     nixos-rebuild build --flake .#naxos
     

   • If evaluation or build fails (e.g. invalid option syntax or dependency conflict), the transaction is immediately aborted and the running system remains untouched.
6. Atomic Switch & Canary Verification:
   • The new generation is activated using nixos-rebuild switch.
   • The canary runner tests daemon connectivity and storage accessibility.
   • If canary verification fails, the system automatically runs:

     "$PREV_GEN/bin/switch-to-configuration" switch
     

   • The user is alerted in the dashboard with full build logs.

---

1-Click Rollback Mechanism

Because every generation is tied to an explicit Git commit and NixOS system profile generation:

• The user can browse the commit history in the Web UI.
• Clicking Rollback checks out the selected commit and activates the previous generation in seconds.
• No database dumps or manual backups are needed for appliance recovery.