# 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.