docs: complete NaxOS architectural specs, migration guides, API reference, and CI workflows

2026-09-04 00:15:21 +02:00
parent 2719f87e9e
commit ce7c125391
11 changed files with 490 additions and 2 deletions
@@ -0,0 +1,46 @@
+# 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`
+```bash
+cd naxos-api
+npm install
+npm test          # Run Vitest test suite
+npm run dev       # Watch mode on port 8088
+```
+
+### Developing `naxos-ui`
+```bash
+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`
+```bash
+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.