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

<!-- code-review-graph MCP tools -->
## MCP Tools: code-review-graph

**IMPORTANT: This project has a knowledge graph. ALWAYS use the
code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
the codebase.** The graph is faster, cheaper (fewer tokens), and gives
you structural context (callers, dependents, test coverage) that file
scanning cannot.

### When to use graph tools FIRST

- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
- **Architecture questions**: `get_architecture_overview` + `list_communities`

Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.

### Key Tools

| Tool | Use when |
|------|----------|
| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
| `get_review_context` | Need source snippets for review — token-efficient |
| `get_impact_radius` | Understanding blast radius of a change |
| `get_affected_flows` | Finding which execution paths are impacted |
| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
| `semantic_search_nodes` | Finding functions/classes by name or keyword |
| `get_architecture_overview` | Understanding high-level codebase structure |
| `refactor_tool` | Planning renames, finding dead code |

### Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use `detect_changes` for code review.
3. Use `get_affected_flows` to understand impact.
4. Use `query_graph` pattern="tests_for" to check coverage.

## graphify

This project has a graphify knowledge graph at graphify-out/.

Rules:
- Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)