# 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:
     ```bash
     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:
     ```bash
     "$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.