107 lines
5.3 KiB
Markdown
107 lines
5.3 KiB
Markdown
# 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.
|