How solverforge/solverforge-ui works
1. Repository purpose and boundary
- solverforge-ui is a Rust crate that packages a browser UI component library for SolverForge scheduler/optimizer apps.
- The key boundary is: consumers integrate either as a Rust crate that serves /sf/*, or as a copied static asset bundle under static/sf/. No npm-based runtime dependency is expected in the host app.
2. Primary delivery model
- The shipped UI is precompiled into two public bundles: sf.css and sf.js, plus versioned variants like sf.<crate-version>.css/js for immutable caching.
- These assets are embedded into the Rust binary via include_dir!, so the crate can serve them directly without external file deployment.
3. Rust server layer
- src/lib.rs exposes the HTTP routing surface, primarily routes(), which mounts the embedded assets under /sf/*.
- In Axum apps, the host router merges solverforge_ui::routes() and typically falls back to the app’s own static file service for everything else.
- This layer is thin: it is mostly an asset server and integration point, not where UI logic lives.
4. JavaScript component layer
- js-src/ contains the shipped runtime UI logic as a set of composable factories on the SF namespace.
- Core components include header, status bar, tabs, modal, table, toast, footer, API guide, button system, and solver/backend orchestration.
- The JS is written as zero-framework browser code; the public API is instance-based and DOM-driven.
5. Solver lifecycle subsystem
- The most important stateful subsystem is createSolver() in js-src/11-solver.js.
- It orchestrates backend job creation, SSE event streaming, pause/resume/cancel/delete actions, snapshot synchronization, and terminal cleanup.
- This subsystem is the bridge between the optimizer runtime and the UI: it translates typed lifecycle events into callbacks and UI state changes.
6. Backend adapter boundary
- createBackend() in js-src/10-backend.js normalizes transport differences across three supported backends: Axum HTTP, Tauri IPC, and generic fetch-based HTTP APIs.
- The backend contract is explicit: create job, stream events, fetch snapshot, analyze snapshot, pause, resume, cancel, and delete.
- This is the main integration boundary for host applications and external SolverForge services.
7. Data flow from solver runtime to UI
- The server/solver emits canonical lifecycle events over SSE or an equivalent event stream.
- createSolver() consumes these events, tracks job ID and snapshot revision, and updates downstream consumers such as the status bar, render callbacks, and lifecycle-specific hooks.
- The important flow is: backend job creation → event stream attachment → lifecycle events → snapshot sync → UI updates.
8. Shared design system and rendering primitives
- css-src/ defines the design system and layout primitives, including tokens, typography, buttons, modal, table, cards, tooltip, footer, animations, and scrollbars.
- The JS component factories depend on these shared CSS classes and tokens, so the visual system and runtime widgets are coupled through a stable class contract.
- 00-core.js provides low-level helpers like DOM element creation and HTML escaping, which are reused across components.
9. Scheduling visualizations
- Two major scheduling surfaces exist: the low-level rail primitives and the higher-level timeline/Gantt views.
- js-src/13-rail.js and 13a-rail-timeline.js implement dense, read-only scheduling timelines and resource rails with exact time geometry, clustering, and viewport synchronization.
- js-src/14-gantt.js wraps Frappe Gantt into a split-pane task scheduling view with a grid/table above and chart below.
- Corresponding CSS lives in 15-rail-resources.css, 16-rail-blocks.css, 17-gantt-layout.css, 18-gantt-bars.css, and 19-rail-timeline.css.
10. Optional module boundary
- static/sf/modules/ contains optional shipped modules, currently a map integration built on Leaflet.
- This is intentionally separated from the core bundle so consumers can opt into it without treating it as the default public surface.
- The map module follows the same pattern as the rest of the repo: static assets plus a browser-side JS facade.
11. Demo and verification surface
- demos/ provides runnable fixtures that exercise the shipped surfaces together: full UI, timeline, dense timeline, and rail primitives.
- tests/ covers backend contracts, solver lifecycle behavior, rendering correctness, accessibility regressions, browser smoke checks, and safe HTML handling.
- This test split reflects the repo’s architecture: backend adapter correctness, state-machine correctness, and DOM rendering correctness are separate concerns.
12. Build, packaging, and release pipeline
- css-src/ and js-src/ are concatenated into distributable bundles by the Makefile and related scripts.
- Release automation in GitHub/Forgejo validates packaging, publishes crates, and tags versioned bundle outputs.
- The publish boundary matters architecturally: source files are development-only, while the shipped crate contains only embedded assets and Rust code required for integration.
13. Typical deployment topology
- In a Rust host app, the UI sits behind the app server under /sf/*, while the app’s own routes serve domain data and solver endpoints.
- In non-Rust hosts, the static/sf/ directory can be copied or mounted as a static asset tree, and the backend adapter can point at any compatible HTTP or IPC solver service.
- The architecture is therefore “embedded asset library + backend contract,” not a monolithic application.
Main entry points: sf.js sf.js · 11-solver.js Solver lifecycle · solver-lifecycle.test.js Tests · 14-gantt.js Gantt view
Components 20
Delivery
Rust entrypoint and embedded static assets served by the crate.
- Crate routes · Exposes the HTTP mount points for embedded UI assets, primarily under /sf/*.
src/lib.rs - sf.css · Public CSS bundle served by the crate and copied static deployments.
static/sf/sf.css - sf.js · Public browser bundle that wires together the shipped UI factories.
static/sf/sf.js
Browser UI
Client-side bundles, components, and visual scheduling surfaces.
- Core helpers · Low-level DOM creation, escaping, and shared helper primitives.
js-src/00-core.js - Design tokens · Shared tokens and base layout rules that define the visual contract.
css-src/00-tokens.css - Backend adapter · Normalizes Axum, Tauri, and generic HTTP backends behind one contract.
js-src/10-backend.js - Solver lifecycle · Orchestrates job creation, SSE events, snapshot sync, and terminal cleanup.
js-src/11-solver.js - Header · Top-level navigation and summary surface for the app shell.
js-src/04-header.js - Status bar · Live runtime status and lifecycle feedback surface.
js-src/05-statusbar.js - Modal · Overlay dialog primitive used by multiple widgets.
js-src/06-modal.js - Tabs · Instance-based tab navigation and section switching.
js-src/07-tabs.js - Table · Data grid and structured list rendering primitive.
js-src/08-table.js - Toast · Transient notification and alert messaging component.
js-src/09-toast.js - API guide · Docs-like browser surface that explains the backend contract.
js-src/12-api-guide.js - Rail view · Dense read-only resource rail and scheduling geometry.
js-src/13-rail.js - Rail timeline · Timeline extension that synchronizes rails with viewport and clusters.
js-src/13a-rail-timeline.js - Gantt view · Split-pane task schedule view built around a chart and table.
js-src/14-gantt.js - Map module · Optional Leaflet-based shipped module under static/sf/modules/.
static/sf/modules/sf-map.js
Connections 31
- Crate routes → sf.css: serves · Mounts the embedded stylesheet under the public UI route.
- Crate routes → sf.js: serves · Mounts the embedded browser bundle under the public UI route.
- sf.js → Core helpers: uses · Bundle includes shared DOM and escaping helpers.
- sf.js → Backend adapter: includes · Browser bundle exposes the transport normalization layer.
- sf.js → Solver lifecycle: includes · Browser bundle exposes solver lifecycle orchestration.
- sf.js → Header: includes · Bundle wires the shell header component.
- sf.js → Status bar: includes · Bundle wires the live status surface.
- sf.js → Modal: includes · Bundle wires the modal primitive.
- sf.js → Tabs: includes · Bundle wires the tab navigation component.
- sf.js → Table: includes · Bundle wires the table component.
- sf.js → Toast: includes · Bundle wires toast notifications.
- sf.js → API guide: includes · Bundle exposes the backend API reference surface.
- sf.js → Rail view: includes · Bundle includes the rail scheduling surface.
- sf.js → Rail timeline: includes · Bundle includes the rail timeline extension.
- sf.js → Gantt view: includes · Bundle includes the Gantt scheduling surface.
- sf.js → Map module: optionally loads · Optional shipped module lives outside the default core surface.
- sf.css → Design tokens: packages · Public stylesheet is built from shared design tokens and layout rules.
- Solver lifecycle → Backend adapter: drives · Solver lifecycle talks to backend job and stream operations.
- Solver lifecycle → Status bar: updates · Lifecycle state feeds live status rendering.
- Solver lifecycle → Toast: notifies · Errors and lifecycle transitions surface through toast messaging.
- Solver lifecycle → Table: renders · Structured snapshots and lifecycle data flow into tables.
- Solver lifecycle → Modal: opens · Terminal or detail interactions can surface in modals.
- Rail timeline → Rail view: builds on · Timeline view extends the lower-level rail primitives.
- Gantt view → Table: pairs with · Gantt uses a table/grid alongside the chart.
- Gantt view → Design tokens: styled by · Schedule views rely on the shared CSS contract.
- Rail view → Design tokens: styled by · Rail geometry and blocks depend on shared layout primitives.
- Demos → sf.js: exercises · Demo pages load the shipped browser bundle.
- Tests → Backend adapter: checks · Validates transport contract behavior.
- Tests → Solver lifecycle: checks · Validates lifecycle and state-machine behavior.
- Tests → Rail timeline: checks · Covers timeline rendering and interaction correctness.
- Tests → sf.js: smokes · Browser checks verify the shipped surface end to end.