# solverforge/solverforge-ui architecture

> Architecture diagram of the GitHub repository solverforge/solverforge-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solverforge/solverforge-ui
- Repository: https://github.com/solverforge/solverforge-ui

## Overview

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: [`static/sf/sf.js`](https://github.com/solverforge/solverforge-ui/blob/main/static/sf/sf.js) (sf.js), [`js-src/11-solver.js`](https://github.com/solverforge/solverforge-ui/blob/main/js-src/11-solver.js) (Solver lifecycle), [`tests/solver-lifecycle.test.js`](https://github.com/solverforge/solverforge-ui/blob/main/tests/solver-lifecycle.test.js) (Tests), [`js-src/14-gantt.js`](https://github.com/solverforge/solverforge-ui/blob/main/js-src/14-gantt.js) (Gantt view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_src_lib["Crate routes<br/>rust router<br/>[lib.rs]"]
  node_sf_css["sf.css<br/>embedded stylesheet<br/>[sf.css]"]
  node_sf_js["sf.js<br/>embedded script<br/>[sf.js]"]
end

subgraph group_browser["Browser UI"]
  node_core["Core helpers<br/>dom utils<br/>[00-core.js]"]
  node_design_css["Design tokens<br/>css system<br/>[00-tokens.css]"]
  node_backend["Backend adapter<br/>transport bridge<br/>[10-backend.js]"]
  node_solver["Solver lifecycle<br/>state machine<br/>[11-solver.js]"]
  node_header["Header<br/>ui component<br/>[04-header.js]"]
  node_statusbar["Status bar<br/>ui component<br/>[05-statusbar.js]"]
  node_modal["Modal<br/>ui component<br/>[06-modal.js]"]
  node_tabs["Tabs<br/>ui component<br/>[07-tabs.js]"]
  node_table["Table<br/>ui component<br/>[08-table.js]"]
  node_toast["Toast<br/>ui component<br/>[09-toast.js]"]
  node_api_guide["API guide<br/>ui component<br/>[12-api-guide.js]"]
  node_rail["Rail view<br/>timeline viz<br/>[13-rail.js]"]
  node_rail_timeline["Rail timeline<br/>timeline viz"]
  node_gantt["Gantt view<br/>schedule viz<br/>[14-gantt.js]"]
  node_map_module["Map module<br/>optional module<br/>[sf-map.js]"]
end

subgraph group_ops["Build & Verify"]
  node_demos["Demos<br/>fixtures<br/>[index.html]"]
  node_tests["Tests<br/>validation"]
end

node_src_lib -->|"serves"| node_sf_css
node_src_lib -->|"serves"| node_sf_js
node_sf_js -->|"uses"| node_core
node_sf_js -->|"includes"| node_backend
node_sf_js -->|"includes"| node_solver
node_sf_js -->|"includes"| node_header
node_sf_js -->|"includes"| node_statusbar
node_sf_js -->|"includes"| node_modal
node_sf_js -->|"includes"| node_tabs
node_sf_js -->|"includes"| node_table
node_sf_js -->|"includes"| node_toast
node_sf_js -->|"includes"| node_api_guide
node_sf_js -->|"includes"| node_rail
node_sf_js -->|"includes"| node_rail_timeline
node_sf_js -->|"includes"| node_gantt
node_sf_js -.->|"optionally loads"| node_map_module
node_sf_css -->|"packages"| node_design_css
node_solver -->|"drives"| node_backend
node_solver -->|"updates"| node_statusbar
node_solver -->|"notifies"| node_toast
node_solver -->|"renders"| node_table
node_solver -->|"opens"| node_modal
node_rail_timeline -->|"builds on"| node_rail
node_gantt -->|"pairs with"| node_table
node_gantt -->|"styled by"| node_design_css
node_rail -->|"styled by"| node_design_css
node_demos -->|"exercises"| node_sf_js
node_tests -->|"checks"| node_backend
node_tests -->|"checks"| node_solver
node_tests -->|"checks"| node_rail_timeline
node_tests -->|"smokes"| node_sf_js

click node_src_lib "https://github.com/solverforge/solverforge-ui/blob/main/src/lib.rs"
click node_sf_css "https://github.com/solverforge/solverforge-ui/blob/main/static/sf/sf.css"
click node_sf_js "https://github.com/solverforge/solverforge-ui/blob/main/static/sf/sf.js"
click node_core "https://github.com/solverforge/solverforge-ui/blob/main/js-src/00-core.js"
click node_design_css "https://github.com/solverforge/solverforge-ui/blob/main/css-src/00-tokens.css"
click node_backend "https://github.com/solverforge/solverforge-ui/blob/main/js-src/10-backend.js"
click node_solver "https://github.com/solverforge/solverforge-ui/blob/main/js-src/11-solver.js"
click node_header "https://github.com/solverforge/solverforge-ui/blob/main/js-src/04-header.js"
click node_statusbar "https://github.com/solverforge/solverforge-ui/blob/main/js-src/05-statusbar.js"
click node_modal "https://github.com/solverforge/solverforge-ui/blob/main/js-src/06-modal.js"
click node_tabs "https://github.com/solverforge/solverforge-ui/blob/main/js-src/07-tabs.js"
click node_table "https://github.com/solverforge/solverforge-ui/blob/main/js-src/08-table.js"
click node_toast "https://github.com/solverforge/solverforge-ui/blob/main/js-src/09-toast.js"
click node_api_guide "https://github.com/solverforge/solverforge-ui/blob/main/js-src/12-api-guide.js"
click node_rail "https://github.com/solverforge/solverforge-ui/blob/main/js-src/13-rail.js"
click node_rail_timeline "https://github.com/solverforge/solverforge-ui/blob/main/js-src/13a-rail-timeline.js"
click node_gantt "https://github.com/solverforge/solverforge-ui/blob/main/js-src/14-gantt.js"
click node_map_module "https://github.com/solverforge/solverforge-ui/blob/main/static/sf/modules/sf-map.js"
click node_demos "https://github.com/solverforge/solverforge-ui/blob/main/demos/index.html"
click node_tests "https://github.com/solverforge/solverforge-ui/blob/main/tests/solver-lifecycle.test.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_lib,node_sf_css,node_sf_js toneBlue
class node_core,node_design_css,node_backend,node_solver,node_header,node_statusbar,node_modal,node_tabs,node_table,node_toast,node_api_guide,node_rail,node_rail_timeline,node_gantt,node_map_module toneAmber
class node_demos,node_tests toneMint
```

## Components

### Delivery

Rust entrypoint and embedded static assets served by the crate.

- [Crate routes](https://github.com/solverforge/solverforge-ui/blob/main/src/lib.rs): rust router · Exposes the HTTP mount points for embedded UI assets, primarily under /sf/*. · `src/lib.rs`
- [sf.css](https://github.com/solverforge/solverforge-ui/blob/main/static/sf/sf.css): embedded stylesheet · Public CSS bundle served by the crate and copied static deployments. · `static/sf/sf.css`
- [sf.js](https://github.com/solverforge/solverforge-ui/blob/main/static/sf/sf.js): embedded script · 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](https://github.com/solverforge/solverforge-ui/blob/main/js-src/00-core.js): dom utils · Low-level DOM creation, escaping, and shared helper primitives. · `js-src/00-core.js`
- [Design tokens](https://github.com/solverforge/solverforge-ui/blob/main/css-src/00-tokens.css): css system · Shared tokens and base layout rules that define the visual contract. · `css-src/00-tokens.css`
- [Backend adapter](https://github.com/solverforge/solverforge-ui/blob/main/js-src/10-backend.js): transport bridge · Normalizes Axum, Tauri, and generic HTTP backends behind one contract. · `js-src/10-backend.js`
- [Solver lifecycle](https://github.com/solverforge/solverforge-ui/blob/main/js-src/11-solver.js): state machine · Orchestrates job creation, SSE events, snapshot sync, and terminal cleanup. · `js-src/11-solver.js`
- [Header](https://github.com/solverforge/solverforge-ui/blob/main/js-src/04-header.js): ui component · Top-level navigation and summary surface for the app shell. · `js-src/04-header.js`
- [Status bar](https://github.com/solverforge/solverforge-ui/blob/main/js-src/05-statusbar.js): ui component · Live runtime status and lifecycle feedback surface. · `js-src/05-statusbar.js`
- [Modal](https://github.com/solverforge/solverforge-ui/blob/main/js-src/06-modal.js): ui component · Overlay dialog primitive used by multiple widgets. · `js-src/06-modal.js`
- [Tabs](https://github.com/solverforge/solverforge-ui/blob/main/js-src/07-tabs.js): ui component · Instance-based tab navigation and section switching. · `js-src/07-tabs.js`
- [Table](https://github.com/solverforge/solverforge-ui/blob/main/js-src/08-table.js): ui component · Data grid and structured list rendering primitive. · `js-src/08-table.js`
- [Toast](https://github.com/solverforge/solverforge-ui/blob/main/js-src/09-toast.js): ui component · Transient notification and alert messaging component. · `js-src/09-toast.js`
- [API guide](https://github.com/solverforge/solverforge-ui/blob/main/js-src/12-api-guide.js): ui component · Docs-like browser surface that explains the backend contract. · `js-src/12-api-guide.js`
- [Rail view](https://github.com/solverforge/solverforge-ui/blob/main/js-src/13-rail.js): timeline viz · Dense read-only resource rail and scheduling geometry. · `js-src/13-rail.js`
- [Rail timeline](https://github.com/solverforge/solverforge-ui/blob/main/js-src/13a-rail-timeline.js): timeline viz · Timeline extension that synchronizes rails with viewport and clusters. · `js-src/13a-rail-timeline.js`
- [Gantt view](https://github.com/solverforge/solverforge-ui/blob/main/js-src/14-gantt.js): schedule viz · Split-pane task schedule view built around a chart and table. · `js-src/14-gantt.js`
- [Map module](https://github.com/solverforge/solverforge-ui/blob/main/static/sf/modules/sf-map.js): optional module · Optional Leaflet-based shipped module under static/sf/modules/. · `static/sf/modules/sf-map.js`

### Build & Verify

Packaging, demos, and automated validation surfaces.

- [Demos](https://github.com/solverforge/solverforge-ui/blob/main/demos/index.html): fixtures · Runnable examples that exercise the bundled UI surfaces together. · `demos/index.html`
- [Tests](https://github.com/solverforge/solverforge-ui/blob/main/tests/solver-lifecycle.test.js): validation · Backend, solver, rendering, accessibility, and browser smoke coverage. · `tests/solver-lifecycle.test.js`

## Connections

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