AGENTS.md

Repository Guidelines

Project Structure & Module Organization

solverforge-fsr is a Rust 1.95 SolverForge field-service routing app with an Axum server and static browser workspace. Rust code lives in src/: domain/ defines planning entities and facts, constraints/ contains scoring rules, solver/ owns retained solver jobs, api/ exposes REST/SSE routes and DTOs, and data/ builds the Bergamo demo dataset. Browser assets live in static/, split by responsibility (app-route-state.js, app-render-routes.js, etc.). Deployment and configuration files are at the repo root: Dockerfile, Makefile, solver.toml, and solverforge.app.toml.

Keep handwritten source, docs, and deployment files under 300 lines; split by module or responsibility when a file approaches that size.

Build, Test, and Development Commands

• make doctor checks local cargo, rustc, node, and docker readiness.
• make run runs the debug server on PORT (default 7860).
• make build-release builds solverforge_fsr in release mode.
• make test runs Rust tests plus frontend JavaScript syntax checks.
• make lint runs cargo fmt --check, clippy with warnings denied, and JS syntax checks.
• make ci-local runs the full Hugging Face Space validation path, including Docker image build.
• make space-run builds and runs the Docker Space image locally.

Coding Style & Naming Conventions

Use idiomatic Rust 2021 with cargo fmt formatting and clippy under -D warnings. Rust modules and files use snake_case; types use PascalCase; functions, fields, and variables use snake_case. Keep API DTOs explicit and snapshot-scoped. Frontend files should stay plain JavaScript modules with clear ownership boundaries rather than large shared scripts.

Testing Guidelines

Place Rust unit tests near the code they cover, using descriptive names such as reports_unreachable_route_segments. Run make test before handing off normal changes and make ci-local before deployment, dependency, Docker, or Space changes. Frontend validation is currently syntax-level via node --check over static/*.js.

Commit & Pull Request Guidelines

History uses conventional commits such as feat(fsr): ..., fix(ui): ..., and chore: .... Keep each commit focused on one revertable intent and include a full body when the change spans behavior, deployment, or dependencies. PRs should describe the user-visible effect, linked issue or review comment, validation commands run, and include screenshots for visible UI changes.

Security & Configuration Tips

Do not commit credentials, local Hugging Face tokens, generated desktop bundles, or build output. Keep Docker/Space builds registry-backed through crates.io dependencies unless the build context explicitly vendors local crates.