WIREFRAME.md

solverforge-lessons WIREFRAME

This file is the architectural map for the lesson timetabling example.

README.md explains how to run and use the app. This document explains how the pieces fit together and where each responsibility lives.

Documentation Roles

• README.md Quick start, dependency shape, API list, and user-facing orientation.
• WIREFRAME.md Architecture, execution flow, and file-map walkthrough.
• AGENTS.md Repo-specific contribution, validation, and documentation rules.
• Makefile Local development, validation, and Space/Docker command surface. Its test-e2e target contains the inline Playwright smoke for this app.
• Dockerfile Hugging Face Docker Space image definition.
• docs/screenshot.png Current browser screenshot embedded by the README.

What This Repo Is Teaching

This repo is a complete solverforge-lessons scalar-variable SolverForge app for weekly lesson timetabling.

It shows how to combine:

• a Plan solution with two scalar planning variables per lesson
• assignment-completeness, hard feasibility, and soft timetable-quality rules
• deterministic LARGE demo-data generation from domain facts
• retained jobs with snapshots, analysis, cancel, pause, resume, and SSE
• a browser timetable workspace built on stock solverforge-ui assets

SolverForge Concepts In Plain Language

• Timeslot, Teacher, Group, and Room Input facts. The solver reads them but does not move them.
• Lesson Planning entity. Each lesson receives a timeslot and a room.
• timeslot_idx and room_idx The two scalar planning variables on Lesson.
• Plan Planning solution. It holds facts, lesson entities, derived indexes, and the current HardMediumSoftScore.
• hard score Teacher/group availability, room capacity, and teacher/group/room conflicts.
• medium score Assignment completeness for timeslot and room decisions.
• soft score Room-kind fit, late slots, and repeated subject days.
• retained job A solve that lives in memory so the UI can stream events, fetch snapshots, pause/resume, cancel, analyze, and delete terminal jobs.

Runtime Flow

1. The browser loads static/index.html.
2. static/app.js loads static/sf-config.json, static/generated/ui-model.json, and solverforge-ui assets from /sf/*.
3. The app fetches /demo-data to discover the default LARGE id, then loads the plan from /demo-data/LARGE.
4. src/data/data_seed/entrypoints.rs dispatches to src/data/data_seed/large.rs.
5. Plan::new() normalizes fact and lesson indexes and filters stale scalar assignment indexes.
6. The browser renders group, room, teacher, data, and REST API views.
7. When the user clicks Solve, the browser posts the current plan to POST /jobs.
8. src/api/routes.rs deserializes PlanDto back into Plan.
9. SolverService starts a retained solve through SolverManager<Plan>.
10. Solver events are converted by src/solver/event_payload.rs into UI-facing JSON.
11. The browser consumes /jobs/{id}/events and fetches snapshots and analysis for exact snapshot revisions.

File Map

.
├── Cargo.toml
│   Rust 1.95 crate metadata for the app package and registry dependency
│   requests.
├── solver.toml
│   Embedded search policy for construction and local search.
├── solverforge.app.toml
│   App metadata, demo IDs, model facts/entities, registry dependency sources,
│   and the `solverforge 0.19.3` runtime target.
├── Makefile
│   Local build, validation, inline browser smoke, and Space/Docker commands.
├── Dockerfile
│   Multi-stage Rust 1.95 Docker image for Hugging Face Spaces.
├── README.md
│   Run guide, dependency shape, API list, and learning path.
├── AGENTS.md
│   Repo-specific rules for future edits.
├── WIREFRAME.md
│   This architectural walkthrough.
├── docs/screenshot.png
│   Current browser screenshot used by the README.
├── src/
│   ├── domain/
│   │   `planning_model!` manifest, facts, `Lesson`, `Plan`, and indexes.
│   ├── constraints/
│   │   One timetable score rule per file plus the assembler in `mod.rs`.
│   ├── data/
│   │   Deterministic `LARGE` demo-data generator and entrypoints.
│   ├── solver/
│   │   Retained-job service and runtime event payload formatting.
│   └── api/
│       DTOs, REST routes, and SSE streaming.
└── static/
    ├── index.html
    ├── sf-config.json
    ├── generated/ui-model.json
    ├── app.js
    │   Browser controller, solver lifecycle, and REST API guide.
    └── views.js
        Timetable view rendering for group, room, and teacher perspectives.

Demo Data

src/data/data_seed/entrypoints.rs exposes one demo ID:

• LARGE

The generator is deterministic. It builds 40 weekly timeslots, 20 teachers, 12 student groups, 300 unassigned lessons, and 10 typed rooms. The initial score is 0hard/-600medium/0soft because each lesson starts without a timeslot and room.

API And Retained Runtime

The REST API handles discovery, job control, and snapshot reads:

• /health and /info expose liveness and app metadata.
• /demo-data and /demo-data/{id} expose the deterministic demo catalog.
• /jobs creates a retained solver job.
• /jobs/{id} and /jobs/{id}/status expose summary state.
• /jobs/{id}/snapshot returns an exact or latest snapshot.
• /jobs/{id}/analysis runs constraint analysis for a snapshot.
• /jobs/{id}/pause, /jobs/{id}/resume, and /jobs/{id}/cancel control a live job.
• DELETE /jobs/{id} removes a terminal retained job.
• /jobs/{id}/events streams typed lifecycle events.

Frontend Layout

static/app.js owns the browser shell, tab state, demo loading, retained-job controls, SSE handling, status bar, and visible REST API guide.

static/views.js owns lesson-specific presentation: group timetables, room usage, teacher load, and data tables. The app intentionally uses an inline Playwright smoke in Makefile instead of a tests/e2e/ directory.

Validation Surfaces

Use the Makefile as the repo-local workflow:

• make fmt-check
• make clippy
• make build-release
• make test
• make test-e2e
• make test-slow
• make space-build
• make ci-local
• make pre-release

make test runs Rust tests, frontend syntax checks, and the inline Playwright browser smoke. make ci-local includes the Docker image build used by the Hugging Face Space.