Spaces:
Paused
Paused
| # Repository Guidelines | |
| ## Project Structure And Naming | |
| `solverforge-fsr` is a Rust 1.95 SolverForge field-service routing app with an | |
| Axum server and static browser workspace. The app package version is declared | |
| in `Cargo.toml`, and the release binary is `solverforge_fsr`. | |
| - `src/domain/mod.rs` owns the `solverforge::planning_model!` manifest. | |
| - `src/domain/field_service_plan.rs` owns the `FieldServicePlan` solution, | |
| transient visit-index normalization, and route shadow refresh hook. | |
| - `src/domain/location.rs`, `service_visit.rs`, and `travel_leg.rs` own the | |
| problem facts. | |
| - `src/domain/technician_route.rs` owns the planning entity and its `visits` | |
| list variable. | |
| - `src/domain/route_metrics.rs` owns route shadow measurement. | |
| - `src/constraints/` owns SolverForge scoring rules, one business rule per file. | |
| Prefer stock `ConstraintFactory` streams; `assigned_visits.rs` keeps the | |
| duplicate-assignment check as a small custom `IncrementalConstraint` because | |
| a grouped stream would count singleton groups as analysis matches. | |
| - `src/data/data_seed.rs` owns `STANDARD` demo assembly and road-matrix | |
| preparation; `src/data/bergamo_*.rs` owns the static locations, visit | |
| profiles, technicians, and shared catalog types. | |
| - `src/api/` owns REST, DTO, route geometry, and SSE surfaces. | |
| - `src/solver/` owns retained-job runtime orchestration. | |
| - `static/` owns the browser workspace, split by responsibility | |
| (`app-route-state.js`, `app-render-routes.js`, etc.). | |
| - `Dockerfile`, `Makefile`, `solver.toml`, and `solverforge.app.toml` define | |
| the deployment and runtime contract. | |
| 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, frontend JavaScript syntax checks, and the | |
| Playwright browser smoke. | |
| - `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 includes `node --check` over `static/*.js`; served | |
| browser behavior is covered by `make test-e2e`. | |
| ## Documentation And Commenting Policy | |
| Assume a reader who is new to Rust and new to planning optimization. | |
| - Keep `README.md`, `WIREFRAME.md`, this file, `solver.toml`, | |
| `solverforge.app.toml`, `static/sf-config.json`, and the visible browser API | |
| guide aligned. | |
| - Keep `docs/screenshot.png` current whenever the visible browser shell changes. | |
| - Add module or function comments where code coordinates SolverForge concepts: | |
| facts, planning entities, variables, retained jobs, road matrices, route | |
| geometry, or score math. | |
| - Explain domain meaning and solver consequences. Do not keep scaffold | |
| placeholders, future-tense planning prose, or comments that merely restate | |
| syntax. | |
| - When docs mention versions, counts, routes, demo IDs, solver policy, or | |
| validation expectations, verify those facts against current code in the same | |
| patch. | |
| ## 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 the declared | |
| crates.io dependency line unless the build context explicitly vendors local | |
| crates. | |