WIREFRAME.md

solverforge-hospital WIREFRAME

This file is the architectural map for beginners.

If README.md tells you how to run the app, this document tells you how the pieces fit together and in which order to read them.

Documentation Roles

The docs in this repo are meant to work together rather than compete:

• README.md Quick start, concepts, and user-facing orientation.
• WIREFRAME.md Architecture, execution flow, and file-map walkthrough.
• docs/api-and-solver-policy.md REST routes, lifecycle semantics, payload shape, and solver policy notes.
• AGENTS.md Rules for keeping code, comments, tests, and docs aligned in future changes.
• Makefile The shared developer command surface, including the local Space validation pipeline.
• docs/screenshot.png Current browser screenshot embedded by the README.

What This Repo Is Teaching

solverforge-hospital is a complete SolverForge example, not just a scoring snippet.

It shows how to build a planning app where:

• the domain model is small and explicit
• the score rules are readable one file at a time
• the dataset is deterministic and intentionally shaped
• the solver runs as a retained background job
• the browser UI watches the solve through REST and SSE

The planning question is:

"For each hospital shift, which employee should be assigned?"

SolverForge Concepts In Plain Language

• Employee Input data. The solver reads it, but does not move it.
• Shift The thing the solver is allowed to assign.
• employee_idx The one real decision variable in this app. It points from a shift to one employee inside Plan.employees.
• hard score Rules that must not be broken, such as missing skills or overlapping shifts.
• soft score Preferences and quality goals, such as honoring desired days or balancing workload.
• retained job A solve that keeps living in memory after it starts, so the UI can poll it, pause it, resume it, stop it through runtime cancel, or inspect snapshots. Delete is terminal cleanup before the next fresh Solve, not the Stop action.

Read Order

If you are new to this repo, read files in this order:

1. src/domain/employee.rs Learn the input facts first.
2. src/domain/care_hub.rs Learn the hospital service-line grouping used by nearby search.
3. src/domain/mod.rs See the planning_model! manifest that lists and exports the model modules.
4. src/domain/plan.rs Learn the planning entity, planning variable, nearby meters, and derived fields.
5. src/constraints/mod.rs See the full score model at a glance.
6. src/constraints/*.rs Read one scheduling rule per file.
7. src/data/data_seed/entrypoints.rs See the public demo-data surface.
8. src/data/data_seed/large.rs See how the published dataset is assembled.
9. src/solver/service.rs See how a domain solve becomes a retained runtime job.
10. src/api/routes.rs and src/api/sse.rs See the HTTP contract.
11. static/app/main.mjs See the browser boot sequence.
12. static/app/shell/ and static/app/schedule/ See how stock solverforge-ui components are adapted to this hospital demo.

Runtime Flow

The shortest way to understand the app is to follow one request all the way through:

1. The browser loads static/index.html.
2. static/app/main.mjs loads config, the generated UI model, and the LARGE demo dataset.
3. The frontend turns the returned PlanDto into schedule rails and side-panel summaries.
4. When the user clicks Solve, the frontend sends the current plan to POST /jobs.
5. src/api/routes.rs converts that HTTP request into a PlanDto.
6. PlanDto::to_domain() rebuilds the in-memory Plan, including derived helper fields the solver expects.
7. SolverService starts a retained solve through SolverManager<Plan>.
8. The solver emits lifecycle, phase, telemetry, best-solution, and analysis events.
9. src/solver/service.rs converts those runtime events into the JSON event shapes expected by the UI.
10. The browser consumes those events over /jobs/{id}/events and updates the visible status, timeline, and analysis panels.

The browser shell also contains a visible REST API guide. That makes static/app/shell/api-guide.mjs part of the documentation surface, not just a UI helper.

File Map

.
├── Cargo.toml
│   Rust crate metadata and registry dependency requests.
├── solver.toml
│   Embedded solver policy. This is the runtime source of truth for search.
├── solverforge.app.toml
│   App metadata used by the surrounding SolverForge tooling.
├── Dockerfile
│   Container build for running the app outside the dev checkout.
├── Makefile
│   Local build, validation, and Docker/Space workflow wrapper.
├── README.md
│   Beginner run guide and learning path.
├── docs/api-and-solver-policy.md
│   REST, payload, lifecycle, telemetry, and solver-policy reference.
├── WIREFRAME.md
│   This architectural walkthrough.
├── AGENTS.md
│   Repo-specific contributor and documentation rules.
├── docs/screenshot.png
│   Current browser screenshot used by the README.
├── src/
│   ├── lib.rs
│   │   Crate root and public module surface.
│   ├── main.rs
│   │   Axum server bootstrap, CORS, static serving, and route composition.
│   ├── domain/
│   │   `planning_model!` manifest plus problem model modules.
│   ├── constraints/
│   │   One scheduling rule per file plus the assembler in `mod.rs`.
│   ├── data/
│   │   Deterministic demo-data generator and published entrypoints.
│   ├── solver/
│   │   Retained-job facade over the SolverForge runtime.
│   └── api/
│       DTOs, REST routes, and SSE streaming.
├── static/
│   ├── index.html
│   │   Browser entrypoint.
│   ├── sf-config.json
│   │   Runtime UI config for the stock frontend shell.
│   ├── generated/ui-model.json
│   │   Generated view metadata used by `solverforge-ui`.
│   └── app/
│       ├── main.mjs
│       │   Browser boot and wiring.
│       ├── shell/
│       │   App shell, state, solver controls, and panels.
│       ├── schedule/
│       │   Hospital-specific grouping, presentation, and rail rendering.
│       └── views/registry.mjs
│           Named view registration.
└── tests/
    ├── frontend/
    │   Browserless frontend tests.
    ├── e2e/
    │   Playwright browser tests for the served app.
    └── support/
        Fake DOM support used by the frontend tests.

Why The Model Looks This Way

This app is intentionally narrow.

• There is one planning entity type: Shift.
• There is one scalar planning variable: employee_idx.
• Nearby search is attached directly to that scalar variable.
• The solver does not juggle multiple variable types, chained assignments, or list planning.

That makes the example easier to learn because the optimization problem stays visible:

• facts live in Plan.employees
• decisions live in Plan.shifts[*].employee_idx
• score rules read those two things and judge the assignment

Why The Demo Data Is Structured

The demo-data generator is not filler.

It is designed to give beginners a problem that is:

• deterministic
• feasible
• interesting enough that local search still has work to do
• stable enough that tests and comparisons stay meaningful

One important design trick is the hidden witness roster in src/data/data_seed/witness.rs.

That internal roster gives the generator a known feasible staffing pattern. The published dataset is then shaped around that witness, while the solver only sees the final public problem. This lets the repo ship a realistic-feeling demo without random feasibility failures.

Why The Runtime Uses REST And SSE

The solve is long-lived compared with a normal request/response handler, so the backend splits the contract into two parts:

• REST for control and snapshots
• SSE for live progress

That separation keeps the frontend simple:

• create a job
• poll or fetch details when needed
• subscribe once to the live event stream

It also mirrors how a real retained SolverForge app behaves in production.

One small but important detail: GET /jobs/{id} and GET /jobs/{id}/status return the same summary payload. The second route exists as a stock-compatible alias for clients that expect the explicit /status URL shape.

Solver Policy

solver.toml is embedded by Plan and is therefore part of the actual model, not a side document.

The shipped search policy is deliberately conservative:

• cheapest_insertion builds a feasible first assignment
• local search stays in the nearby scalar neighborhood
• late_acceptance and accepted_count keep the search moving without blowing up step cost

That narrow configuration is intentional for this demo. It is the balanced 30-second policy that currently performs best on the hospital dataset.

Frontend Design

The frontend is intentionally thin.

This repo is not trying to teach a custom framework. It is showing how to take stock solverforge-ui pieces and adapt them to one concrete planning problem.

• shell/ owns app lifecycle, backend wiring, and side panels
• schedule/ owns the hospital-specific transformation from domain data to visual rails
• tests in tests/frontend/ lock browserless presentation behavior down
• tests in tests/e2e/ verify the served browser app with Playwright

Validation Surfaces

When you change this repo, think in six separate layers:

1. Domain and constraint logic: make test-rust
2. Slow end-to-end solve quality: make test-slow
3. Frontend module correctness: make test-frontend-syntax
4. Frontend module behavior: make test-frontend
5. Served browser behavior: make test-e2e
6. Local deploy readiness for the Docker-based Space target: make ci-local

If you keep those six layers green, the repo remains teachable and usable.