# RosterWeave Technical Design

## Goals

RosterWeave produces understandable schedules for small teams without an external solver. The design prioritizes deterministic output, explicit constraints, testability and stable data interchange. It deliberately does not claim global optimality.

## Architecture

The root package contains cooperating layers for immutable domain models, validation, constraints, scoring, deterministic search, explanation, input/output and resilience analysis. The CLI depends only on the public package, proving the exported API is sufficient for a real consumer.

## Solver

Shifts are ordered by scarcity: fewer eligible workers, more skill requirements and greater headcount increase difficulty. Skill requirements are filled before general headcount. Candidates are sorted by objective delta and a deterministic seed-derived tie breaker. Bounded local search attempts worker moves and keeps only strict improvements that preserve hard constraints.

## Objective

The objective is a weighted sum of understaffing, skill shortage, workload deviation, night/weekend spread, preference cost and overtime. `ScoreBreakdown` exposes every component so users can understand trade-offs.

## Resilience analysis

Capacity analysis measures available and eligible worker margins per shift and skill. Sensitivity analysis removes one worker at a time, resolves the problem and compares feasibility, coverage, objective and newly critical shifts. Recommendations translate these measurements into backup and cross-training actions.

## Determinism, safety and compatibility

Input arrays, seed and configuration determine output. The library performs no network access and writes no files. Produced schedules are decision support and require human review in regulated environments. WebAssembly is the canonical target; core code avoids platform-specific APIs.