@exellix/jobs-ui

Jobs dashboard — React operator SPA for the Exellix job factory. Monitor queue health, browse Memorix information and graph outputs, inspect the run journal, configure ongoing work and on-demand batches, and analyze pipeline performance.

| Package | Role | |---------|------| | @exellix/jobs | Jobs manager — queue runtime, worker loop, CLI | | @exellix/jobs-api | Jobs HTTP API — REST server this UI talks to | | @exellix/jobs-ui (this) | Jobs dashboard — React SPA only | | @exellix/jobs-db | Jobs data tier — Mongo persistence |

A factory run is one graph execution on one information item. Continuous work and on-demand flows both enqueue runs into the same journal. See temp/jobs/ for the design.

Migration from 1.x: @exellix/[email protected] bundled the HTTP API and dashboard in one package. 2.x is dashboard-only — use @exellix/jobs-api for the REST server and programmatic queries.

Core concepts

Information items (not just “database records”)

The UI speaks in operator terms — Information and item — but the API and Memorix layer still use record in paths and types (core-records, recordId, etc.). Treat those as the same idea: one processable unit of information that a pipeline can run on.

That unit is not limited to a classic entity row. What it is depends entirely on how the object type is modeled in Schema UI and stored in Memorix. Examples:

| What you might process | Typical Memorix shape | |------------------------|------------------------| | A business object (asset, ticket, person) | Core record on an entity | | A document, page, or media asset | Content in a scoped content type | | One chat turn | A row in a messages / content collection | | An entire conversation | The core record for a chat entity (with related message content assembled at run time) | | A time-stamped occurrence | An event record | | A knowledge article or embedding source | A knowledge record | | Graph output from a prior run | A row in a processing-output collection (shown under Outputs) |

So “record” here means whatever your schema defines as the input identity for a run — not necessarily a single Mongo document in core, and not necessarily one physical row if you merge related content types when queuing.

For the job factory:

• One factory run = one item — identified by entity + collection + id (plus optional related content pulled in as context).
• Narratives tag items for matching (ongoing work and batch selection) — e.g. “needs summary”, “high priority”.
• Processing stamps track which pipelines have touched an item and whether they succeeded.
• Assembly (on-demand single) lets you choose which content types and fields are merged into graph input without changing which item the run is for.

Browse and inspect items under Information (inputs) and Outputs (saved pipeline results). The journal always refers back to the item that was processed, whatever shape it had.

Install

npm install @exellix/jobs-ui

The dashboard requires a running @exellix/jobs-api instance (or any host serving the same /api/* contract).

Quick start

Recommended — one command starts API, queue worker, and UI (needs MONGO_URI in graph-packages/graph-engine/.env):

npm run dev            # from jobs-ui — full stack via scripts/dev-jobs.mjs
# or from monorepo root:
npm run dev:jobs

| URL | Service | |-----|---------| | http://localhost:5190 | Dashboard (Vite, proxies /api) | | http://localhost:3099 | jobs-api REST server |

Split terminals (UI-only with HMR against an API you start separately):

# terminal 1 — API backend
cd ../jobs-api && npm run serve

# terminal 2 — UI only
npm run dev:ui         # Vite on :5190, proxies /api → http://localhost:3099

Dev configuration

| Variable | Default | Effect | |----------|---------|--------| | VITE_API_PROXY | http://localhost:<PORT> | API target for the Vite /api proxy (PORT from jobs-api/.env, default 3099) | | VITE_DEV_PORT | 5190 | Vite dev server port |

Combined deploy (single port)

Build the UI, then let the API serve it:

npm run build
cd ../jobs-api && JOBS_UI_STATIC_DIR=../jobs-ui/dist npm run serve

When the API sets JOBS_UI_TOKEN, the SPA must send Authorization: Bearer <token> on /api/* requests (configure at the reverse proxy or API layer).

Architecture

• React 19 SPA with React Router and TanStack Query for data fetching and cache invalidation.
• All data flows through web/src/api/real.ts → /api/* on the jobs-api host. There is no mock mode in 2.x and no local playground/ fixtures — Live Console activities come from Activix on Mongo via GET /api/factory-runs/:id/activities. Configure MONGO_URI and ACTIVIX_STORAGE_MODE=database in jobs-api/.env (not in jobs-ui).
• Agent scope — the top-bar AgentScopeSelect (@x12i/memorix-agents) filters entities, ongoing work, information lists, and journal views to a single Memorix agent when selected. Persisted in localStorage under exellix-memorix-ui.selected-agent.
• Queue manager — compact pause/resume control in the top bar; full card on Settings. Polls queue settings every 10s.
• Infinite scroll — Information browse and Journal list load pages on demand via useCoreRecordsInfinite / useFactoryRunsInfinite.

Navigation

| Nav item | Route(s) | Purpose | |----------|----------|---------| | Overview | / | Factory health, status counts, throughput chart, recent failed/running/pending runs | | Work | /work, /work/new, /work/:id | Ongoing (continuous) work definitions | | On-Demand | /on-demand, /on-demand/single, /on-demand/batch, /on-demand/batch/:id | Ad-hoc single-item and batch runs | | Information | /information, /information/:recordId | Browse Memorix information items (any schema-defined processable unit) | | Outputs | /outputs, /outputs/:recordId | Browse graph output collections and saved results | | Journal | /journal, /journal/:id | Factory run list and per-run inspection | | Pipeline analytics | /pipelines, /pipelines/:graphId, /pipelines/entity/:entityName | Aggregated performance by pipeline or entity | | Settings | /settings | Queue manager, concurrency, admission interval | | Item timeline (legacy) | /items/:itemId | Multi-run DAG timeline for a single item ID |

Legacy redirects

Older bookmarks still resolve:

| Old path | Redirects to | |----------|--------------| | /records, /records/:id, /sources | /information | | /runs, /runs/:id | /journal | | /job-defs, /job-defs/:id | /work | | /jobs/new | /on-demand |

Features by area

Overview (/)

• Live status cards for all run states: blocked, pending, running, done, failed, cancelled — click a card to open Journal filtered by that status.
• Filters: source type (continuous / on-demand single / on-demand batch), ongoing work, entity.
• 24-hour throughput chart.
• Preview columns: recent failed, currently running, oldest pending (with inline cancel for pending/blocked).
• Subtitle shows job manager state (running/paused), active slot usage, and selected agent scope.

Ongoing work (/work)

Continuous work definitions poll Memorix on a schedule, match items by narratives and processing rules, and enqueue factory runs automatically.

List — name, status (active/inactive), entity, narratives, reprocessing mode, graph, re-scan interval, last scan, jobs created, last evaluation result. Actions: evaluate now, activate/deactivate.

Create wizard (/work/new) — same Input → data sources → narratives head as on-demand, then a batch-like tail, plus ongoing-work-specific execution policy:

1. Basic info — name, description, object type, optional context (linked/same-object sources)
2. Data sources — content types merged into graph input (snapshots preferred by default)
3. Narratives — select information tags on the entity
4. Process — graph or skill
5. Result writeback — simulation, graph default, same-entity inferences, or custom destination
6. Prerequisites — reprocessing TTL/skip, exclude in-flight, required graphs, cross-entity prerequisites
7. Properties — assembly selection (which content types/fields feed the graph)
8. Execution policy — re-scan interval (5 min – 24 h), priority
9. Review — create inactive or create and activate

Detail (/work/:id) — tabs:

• Overview — configuration, schedule, jobs created, estimated matching
• Evaluations — history of each scan cycle (matched, created, excluded)
• Matching Information — live preview of items that would match current rules
• Runs — infinite-scroll journal filtered to this work definition
• Settings — edit name, narratives, processing, graph, result writeback, properties, policy; exclusion panel for last evaluation

On-Demand (/on-demand)

Hub — choose single item or batch mode.

Single item (/on-demand/single) — seven-step wizard:

1. Input — object type, optional context (linked/same-object sources)
2. Choose item — data sources, optional narrative filter, pick a specific item or a random sample
3. Process — graph or skill
4. Result writeback — simulation, graph default, same-entity inferences, or custom persistency
5. Properties — assembly selection (which content types/fields feed the graph)
6. Review & run — priority, summary
7. Done — action result with link to journal entry

Supports deep-link ?entity= from Information detail.

Batch (/on-demand/batch) — same Input → data sources head as single-item, then batch-specific narratives, then the same tail:

1. Input — object type, optional context
2. Data sources — content types merged into graph input for every item in the batch
3. Narratives — filter which items are included
4. Process — graph or skill
5. Result writeback — simulation, graph default, inferences, or custom destination
6. Processing prerequisites — reprocessing, exclude in-flight, prerequisites, queue overlap policy
7. Properties — assembly selection
8. Review & queue — matching preview, writeback summary, batch name, priority
9. Queued — batch created; link to batch detail

Batch detail (/on-demand/batch/:id) — status counts, selection summary, excluded items panel, infinite-scroll run list.

Information (/information)

Browse Memorix items for an entity — see Information items above. The default view is the entity’s core collection, but an “item” may represent a full object, a content slice, a message, a chat, or any other shape your schema defines.

• Filters: entity, collection (core and related), narratives (chip multi-select), processed-by graph, processing status (succeeded / failed / running / queued / not-processed / unknown).
• Infinite-scroll table with dynamic scalar columns from the first row.
• Actions: run on-demand for entity, create batch from current filter.
• Row click → item detail.

Item detail (/information/:recordId?entity=&collection=) — tabs:

• Core — id, entity, label, scalar fields, timestamps
• Narratives — assigned tags with provenance
• Processing — per-graph processing stamps and status; Associated enrichment (preview) panel to configure linked-object joins, target associated* property (auto-suggested from content type), advanced filter, mandatory flag, and preview smart-merge for this item
• Snapshots — Memorix snapshot history
• Journal — factory runs for this item (infinite scroll)

Shortcut: Run on-demand pre-fills the single-item wizard.

Outputs (/outputs)

Same browse UI as Information, scoped to processing-output collections.

• Filter by entity and output collection.
• Clear collection — typed confirmation ({entity}-{collection}) deletes all items in that output collection and clears linked stamps.
• Item detail — Output tab (full JSON document), Journal tab; delete a single saved result.

Journal (/journal)

Factory run list with infinite scroll.

• Scope: total / today / this week / this month.
• Filters: status, source type, ongoing work, batch, graph, entity, record ID.
• When filtered by batch with failures, banner links to Recover batch on batch detail.
• Bulk cancel for pending/blocked runs (multi-select).
• Status count chips from API.

Run detail (/journal/:id) — tabs:

• Overview — summary, source link (work or batch), processing result card, queue admission state, stale-running warning
• Console — live event stream while running (auto-refresh 1.5s)
• Pipeline — execution diagram and performance panel (duration, tokens, cost per node)
• Input & Output — assembled input, graph result, Memorix writeback (RunIoPanel)
• Details — raw metadata, assembly selection, related records, error trace

Actions: Re-run (new journal entry), Execute now (inline worker), Run next when slot available, Retry same entry, Cancel.

Transient infrastructure failures (Mongo blips, timeouts) retry automatically up to max attempts (app default 4 for batches — configure under Settings → Transient failure retries). Run detail shows scheduled retries and exhausted-attempt hints.

On-demand batch (/on-demand/batch)

Multi-step wizard: input → data sources → narratives → process → writeback → processing → properties → review.

• Max retries per batch (falls back to app default).
• Preflight runs automatically on review when ≥50 items are eligible — blocking issues disable Queue batch (same as CLI --preflight).
• Recent batches on the On-Demand hub (/on-demand) with progress and failed counts.

Batch detail (/on-demand/batch/:id):

• Accounting headline (matched → queued, skips, failures).
• Failure breakdown by cause with sample journal links.
• Recover batch — resume paused queue + retry all failed runs.
• Retry failed only — bulk retry without changing queue mode.

Settings (/settings)

• Job manager card — pause/resume with running/pending/held counts.
• Queue execution — max concurrent jobs, admission check interval (15s – 2 min).
• Transient failure retries — default max attempts for batch jobs and ongoing work (default 4). Saved via PUT /api/settings.

Pipeline analytics (/pipelines)

Two modes (tab switcher):

• By pipeline — pick a graph; see aggregate runs, success rate, duration/token/cost stats per node and sub-step; execution diagram; performance guide.
• By entity — roll up all graphs for an entity.

Drill-down routes: /pipelines/:graphId, /pipelines/entity/:entityName.

Links from run detail and journal rows open the matching pipeline view.

Global controls (top bar)

• Queue manager toggle — pause/resume without leaving the current page.
• Agent scope — filter multi-tenant Memorix agents; affects entity lists, work, information, journal, and pipeline entity mode.
• Runtime badge — Mongo database and host from GET /api/config.

Shared UI building blocks

| Component | Used for | |-----------|----------| | Wizard / WizardSteps | Multi-step create flows (work, on-demand) | | GraphChooser | Entity-compatible pipeline picker | | NarrativeChecklist | Narrative multi-select | | CollectionSourcePicker | Core vs auxiliary collections | | MatchingPreview | Count/sample of items matching selection rules | | PrerequisitesEditor | Reprocessing and cross-graph prerequisites | | ResultWritebackEditor | Where graph results are saved (simulation, AI Processing sub-types discovery/analysis/decision/narrative, graph default, or custom) | | JobContextSourcesEditor | Optional linked/same-object context sources, configured up front on the Input step (runtime linked-information; preview via POST /api/context/preview) | | AssociatedEnrichmentBuilder | Persistent associated* enrichment config + preview merge (Record detail → Processing tab; calls POST /api/associated-enrichment/preview — no write) | | ContentTypeAssembler | Assembly selection — which content types/fields feed the graph, on the Properties step | | PipelineExecutionDiagram / PipelinePerformancePanel | Run and aggregate analytics | | ExclusionPanel | Why items were skipped in evaluations/batches | | BatchAccountingHeadline | Matched → queued → skipped/failed summary on batch pages | | MaxAttemptsField | Per-batch/work max transient retry attempts | | InfiniteScrollFooter | Paginated list footers | | LiveConsole | Streaming run events | | DagView | Item-level multi-run dependency graph (/items/:itemId) |

Scripts

npm run build       # vite build → dist/
npm run dev         # API + queue worker + UI (full local stack)
npm run dev:ui      # Vite only — requires jobs-api on :3099
npm run dev:all     # same as npm run dev
npm test            # build smoke test, graph-picker + pipeline-performance unit tests
npm run test:watch  # vitest watch mode

API contract

The UI expects the full jobs-api surface documented in jobs-api. Key groups used by the dashboard:

• Health / config — /api/health, /api/config
• Queue settings — GET|PUT /api/settings, POST /api/queue/push
• Factory runs — list, detail, execute, retry, cancel, queue-next, activities
• Work factory — work CRUD, evaluate, batches, on-demand single/batch
• Memorix records — entities, narratives, core-records, clear/delete, processing stamps
• Selection / processing — matching preview, assembler properties/preview, context preview, associated-enrichment preview
• Not yet consumed by this UI — POST /api/graph/input-coverage (per-context-source resolved/missing/filtered coverage) exists on jobs-api for external/programmatic preflight but has no dashboard surface yet; batch/work review steps use validate-sample (assembly gaps) instead
• Stats — throughput, stuck (overview/journal helpers)
• Agents proxy — /api/agents/* for AgentScopeSelect

License

exellix-license