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

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

Red — Write a failing test that specifies the desired behaviour before writing any implementation code.
Green — Write the minimal implementation to make the test pass. Do not over-engineer.
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

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

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

5.3 KiB Raw Blame History