Spaces:
Sleeping
Sleeping
| # Repository Guidelines | |
| ## Project Structure And Naming | |
| This repo follows the current `solverforge-cli` app shape. The app package | |
| version is `1.0.1`, and the release binary is `solverforge_deliveries`. | |
| - `src/domain/mod.rs` owns the `solverforge::planning_model!` manifest. | |
| - `src/domain/plan.rs` owns the `Plan` planning solution. | |
| - `src/domain/delivery.rs` owns the `Delivery` problem fact. | |
| - `src/domain/vehicle.rs` owns the `Vehicle` planning entity and its | |
| `delivery_order` list variable. | |
| - `src/domain/preview.rs` owns transport/view preview structs. | |
| - `src/domain/route_metrics/` owns route preparation, CVRP hooks, scoring | |
| preview, route geometry, and insertion ranking. | |
| - `src/constraints/` owns one score rule per file plus `mod.rs` assembly. | |
| - `src/data/data_seed/` owns deterministic city demo-data modules with grouped | |
| visit files for scaled delivery counts. | |
| - `src/api/` owns REST, DTO, and SSE surfaces. | |
| - `src/solver/` owns retained-job runtime orchestration. | |
| - `static/app/models/` owns frontend plan modeling. | |
| - `static/app/ui/` owns browser layout and rendering helpers. | |
| Keep the canonical solution name `Plan`. Do not reintroduce `DeliveryPlan` or | |
| `delivery_plan.rs`. | |
| ## File Size Rule | |
| No source, test, frontend, config, or repo documentation file should reach 300 | |
| lines. Split by responsibility before that point. Large generated/cache output | |
| under `target/` and `.osm_cache/` is outside this rule. | |
| ## Build And Validation Commands | |
| - `make help` shows the supported command surface. | |
| - `make run-release` runs the app locally on `:7860`. | |
| - `make test` runs Rust, frontend, and Playwright browser tests. | |
| - `make test-e2e` runs the real browser Playwright smoke. | |
| - `make space-build` builds the Docker image used by Hugging Face Spaces. | |
| - `make space-run` builds and runs that image locally. | |
| - `make ci-local` runs formatting, clippy, release build, standard tests, and | |
| the Space Docker image build. | |
| - `make test-live-road` runs the env-enabled road-network smoke test. | |
| - `make pre-release` runs `ci-local` and the live road-network smoke. | |
| - `cargo test` runs Rust unit and integration tests. | |
| - `node --test tests/frontend_models.test.mjs` runs frontend model tests. | |
| Use the Makefile as the authoritative local workflow, matching the | |
| `solverforge-hospital` Space/Docker validation standard. | |
| ## No Suppression Policy | |
| Do not add warning suppressions, fallback compatibility branches, or unused | |
| helper modules. If a split creates unused code, restructure the modules so each | |
| compiled item is used by its crate. | |
| ## Documentation Policy | |
| Keep `Cargo.toml`, `Cargo.lock`, `Makefile`, `Dockerfile`, `README.md`, | |
| `WIREFRAME.md`, `AGENTS.md`, `docs/screenshot.png`, | |
| `solverforge.app.toml`, `solver.toml`, `static/sf-config.json`, and the visible | |
| API guide in | |
| `static/app/ui/api-guide.mjs` aligned. | |
| When changing routes, solver policy, demo IDs, dependency sources, file layout, | |
| or browser behavior, update the docs and screenshot in the same patch. Prefer | |
| current-state documentation over planning language. | |
| ## Testing Guidance | |
| Add Rust unit tests next to the behavior they protect. Add API integration | |
| coverage under `tests/api_contract/` and shared integration helpers under | |
| `tests/support/` only when every helper is used by the single | |
| `tests/api_contract.rs` crate. Add frontend model tests in | |
| `tests/frontend_models.test.mjs`, and browser-flow tests in `tests/e2e/`. | |
| Road-network tests should stay env-gated unless the test uses only cached or | |
| straight-line behavior. Use `SOLVERFORGE_RUN_LIVE_TESTS=1` through | |
| `make test-live-road` when validating live map/routing paths. | |
| ## Runtime Notes | |
| `solver.toml` is embedded by `Plan` through the planning-solution macro. Treat | |
| it as the solver policy source of truth. | |
| `Cargo.toml` currently uses Rust `1.95` and crates.io dependency declarations. | |
| Keep every direct dependency declaration, `solverforge.app.toml`, `Cargo.lock`, | |
| and docs truthful if dependency sources or versions change. | |
| The app serves stock `solverforge-ui` assets, local static app modules, and | |
| Axum API routes from one process. Retained solver jobs are controlled through | |
| REST and observed through SSE. | |