Spaces:
Running
Running
| # 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. | |