naxos-docs/docs/development/contributing.md

NaxOS Developer & Contribution Guide

Repository Structure under naxos Organization

The NaxOS ecosystem is structured across dedicated repositories on Gitea (git.lholz.de/naxos):

1. naxos-os: The core NixOS distribution flake, modules, profiles, and bootable ISO installer.
2. naxos-api: The TypeScript management daemon, ZFS driver, GitOps engine, and unit tests.
3. naxos-ui: The React 18, Tailwind CSS, and CNCF Perses web dashboard.
4. naxos-docs: Architectural blueprints, end-user tutorials, and migration guides.

---

Local Development Workflow

Developing naxos-api

cd naxos-api
npm install
npm test          # Run Vitest test suite
npm run dev       # Watch mode on port 8088

Developing naxos-ui

cd naxos-ui
npm install
npm run dev       # Vite development server on port 3000
npm run build     # Production compile

Testing NixOS Modules in naxos-os

cd naxos-os
nix flake check
nix eval .#nixosConfigurations.naxos.config.system.build.toplevel.drvPath

---

Gitea Actions CI/CD Workflows

Each repository includes automated Gitea Actions workflows in .gitea/workflows/:

• naxos-os: Automated ISO build, flake check, and release artifact generation.
• naxos-api: Automated lint, typecheck, and unit testing.
• naxos-ui: Automated frontend build and artifact packaging.
• naxos-docs: Documentation validation.