Skip to content

README.md

Latest commit

 

History

History
131 lines (92 loc) · 3.68 KB

README.md

File metadata and controls

131 lines (92 loc) · 3.68 KB
Raw

ZenBPM UI

Web interface for ZenBPM - a Business Process Management engine.

Getting Started

Prerequisites

  • Node.js 22.12+
  • pnpm

Installation

# Set correct Node.js version (requires nvm)
nvm use

# Install dependencies
pnpm install

Environment Configuration

Copy the example environment file to create your local configuration:

cp .env.local.example .env.local

Edit .env.local to customize your settings. The file contains detailed documentation for all available options including:

  • API Base URL - Backend server location
  • API Strategy - Choose between mocks, live backend, or mixed mode
  • Mock Delay - Control response timing for development
  • Endpoint Exceptions - Fine-grained control over which endpoints use mocks vs live

Note: .env.local is gitignored and won't be committed. Each developer maintains their own local configuration.

Development

# Start with mocks (default, no backend required)
pnpm dev

# Start with live backend
pnpm dev --mode live

End-to-end tests

The default suite starts the UI with mocked API responses:

pnpm test:e2e

The live suite targets a deployed UI when E2E_BASE_URL is set. Without it, Playwright starts the UI on port 3000 in live mode, so a backend must already be available according to the local Vite environment configuration.

E2E_BASE_URL=https://demo.example.com pnpm test:e2e:live

In CI, the live suite runs on the repository-scoped self-hosted runner labeled vpn, which inherits access to the private ui-dev.zen DNS zone from its host. Configure the E2E_BASE_URL repository variable as http://ui-dev.zen. The mocked Playwright suite does not need VPN access and can run on a GitHub-hosted runner.

At the beginning of every live run, Playwright deploys the BPMN and DMN fixtures used by the process scenarios. Their visible names share one YYYYMMDDHHmmss_ prefix generated by globalSetup; definition keys returned by the backend are passed to the tests internally and require no repository variables. Because this mutates the target environment, do not point the live suite at production.

Build metadata

The application footer displays the UI build version and 12-character commit alongside the metadata returned by GET /system/status. The System Status page shows version, commit, branch, and build time for both ZenBPM and the UI. Frontend metadata is embedded when Vite starts or builds; the browser never invokes Git.

The UI version comes from info.version in openapi/api.yaml. By default, Vite reads the commit and branch from Git, shortens the commit to 12 characters, and records the current UTC time. Builds outside a Git checkout can supply the metadata explicitly:

VITE_BUILD_COMMIT=7af392e12345 \
VITE_BUILD_BRANCH=main \
VITE_BUILD_TIME=2026-08-10T08:00:00Z \
pnpm build

Docker accepts the same values as build arguments. The release workflow resolves and supplies all three automatically:

docker build \
  --build-arg VITE_BUILD_COMMIT=7af392e12345 \
  --build-arg VITE_BUILD_BRANCH=main \
  --build-arg VITE_BUILD_TIME=2026-08-10T08:00:00Z \
  -t zenbpm-ui .

Quality Checks

Before submitting a PR, ensure all quality checks pass:

pnpm check

This runs:

  • ESLint - Code style and best practices (zero warnings allowed)
  • TypeScript - Type checking

PRs must pass pnpm check without any errors or warnings to be merged.

You can also run checks individually:

pnpm lint        # ESLint only
pnpm typecheck   # TypeScript only

Tech Stack

  • React 19 + TypeScript
  • Vite
  • Material UI (MUI)
  • TanStack Query
  • MSW (Mock Service Worker) for API mocking
  • bpmn-js for BPMN diagrams