# XCE Cluster Management System

## Overview
XCE is an HPC cluster management system providing job scheduling, queue management, and cluster resource control. The Go-based API/CLI tier fronts C/C++ system daemons (controller, worker, scheduler).

## Tech Stack
- **Go 1.23.4**: REST API server (`src/frontend/apiserver`), CLI tool (`src/frontend/xcecli`)
- **C/C++**: Core daemons — controller, worker, scheduler, shared lib
- **Build**: Meson + Nix flakes for C components; `make` for Go components
- **Go key deps**: Gin v1.10.0, JWT v4, Zap logging, Viper config, Cobra CLI

## Development Commands
```bash
# From src/frontend/
make build-server       # Build apiserver binary → /tmp/apiserver
make build-cli          # Build xcecli binary → /tmp/xce_static (CGO_ENABLED=0)
make test               # Unit tests (no live server required)
make test-integration   # Regression suite (requires XCE_BIN and SRV_URL env vars)
make test-all           # Unit + integration tests

# Full dev build — all components (from src/)
nix develop                                      # Enter dev environment
meson setup build && ninja -C build              # Build everything (all components)

# Nix package builds (from src/)
nix build --option sandbox false .#xcecore       # C daemons + frontend/apiserver
nix build --option sandbox false .#xcecore_debug # Same with debug/ASAN
nix build --option sandbox false .#xcecli        # CLI tool only
```

## Test-Driven Development
Follow TDD strictly throughout the full development process:

1. **Red** — Write a failing test that specifies the desired behaviour before writing any implementation code.
2. **Green** — Write the minimal implementation to make the test pass. Do not over-engineer.
3. **Refactor** — Clean up the implementation and tests while keeping all tests green.

### Rules
- Never implement a feature without a corresponding test written first.
- Tests must be runnable without a live server or external services (use table-driven tests, stubs, and `t.TempDir()` for fixtures).
- A change is not complete until `make test` (and `make test-integration` where applicable) passes.
- For C components, add a test case in the relevant `testsuite/` before modifying the implementation.
- Tests live next to the code they cover (`_test.go` for Go, `testsuite/` for C).
- Keep test scope narrow — unit-test business logic; use integration tests for HTTP/API surface.

## Architecture
```
Request → Gin Router → Middleware (CORS/RateLimit/IPWhitelist/JWT) → RBAC Check → Controller → Services → In-Memory Store
```
- **3 independent Go modules**: `apiserver`, `xcecli`, `bcctool` (no go.work)
- **Stateful API server**: in-memory stores seeded at startup via `store.LoadBuiltinData()`
- **Pluggable auth**: configfile / LDAP / OAuth2 / PAM (set in `config/auth.yaml`)
- **RBAC**: domain-based role-action-domain model loaded from `config/rbac.yaml`

## Key Files
- `src/frontend/Makefile` — primary build/test orchestration
- `src/frontend/apiserver/cmd/main.go` — server startup, init sequence
- `src/frontend/apiserver/router/routers.go` — all routes and middleware chain
- `src/frontend/apiserver/controllers/rbac_check.go` — RBAC loading and enforcement
- `src/frontend/apiserver/config/rbac.yaml` — role/permission definitions
- `src/frontend/apiserver/config/auth.yaml` — auth provider selection

## Subdirectory Guidelines
- `src/frontend/` — See `src/frontend/CLAUDE.md`
- `src/controller/` — See `src/controller/CLAUDE.md`
- `src/worker/` — See `src/worker/CLAUDE.md`
- `src/scheduler/` — See `src/scheduler/CLAUDE.md`
- `src/lib/` — See `src/lib/CLAUDE.md`