# 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.