- rewrite architecture, development, mcp and scenario docs to match the current code: single container, all mcp tools, runs, versioning, timeouts, settings, client routing and dev setup - rewrite README as a general overview without liquio-specific wording - remove the unused KEYS_DIR setting and ./keys compose mount - remove the unused result parameter from step code execution - complete .env.example with the file storage settings and fix the DB_PATH default
8.4 KiB
Development
Prerequisites
- Node.js 24+ (required by
enginesinpackage.json; the Docker image uses Node.js 24) - Docker + Docker Compose
The repository is a npm workspace monorepo with two packages:
| Workspace | Directory | Description |
|---|---|---|
server |
server/ |
NestJS API + MCP server |
client |
client/ |
React 19 + Vite admin UI |
Install all dependencies from the repo root:
npm install
npx playwright install --only-shell chromium # first time only: headless Chromium for the server
Copy .env.example to .env and fill in the required values before running.
Environment variables (server)
All settings are validated at startup by server/src/config/app.config.ts.
| Variable | Default | Description |
|---|---|---|
NODE_ENV |
development |
Shown in the startup log |
PORT |
3000 |
HTTP port |
DB_PATH |
data/liqa.db |
SQLite database file |
FILES_DIR |
data/files |
Where scenario files and run artifacts are stored |
FILE_RUN_EXPIRATION_DAYS |
7 |
How long run artifacts (downloads, failure dumps, traces) are kept |
FILE_CLEANUP_CRON |
0 3 * * * |
When expired files are deleted |
SESSION_IDLE_TIMEOUT_MINUTES |
30 |
Idle timeout before open sessions are closed |
SESSION_DELETE_CLOSED_DAYS |
7 |
Retention period for closed sessions |
PLAYWRIGHT_TRACE_MODE |
off |
Default Playwright trace mode for runs: on, retain-on-failure or off (see scenario.md) |
CLIENT_DIR |
(empty) | Directory with the built client to serve at / (the Docker image sets it to client); empty means the server doesn't serve the UI |
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH |
(Playwright default) | Path to a Chromium binary to use instead of Playwright's own. Not set in Docker: the image ships Playwright's chromium-headless-shell (matching the Playwright version) under PLAYWRIGHT_BROWSERS_PATH=/ms-playwright. |
Starting the application
Server
Development (watch mode, restarts on file changes):
npm -w server run start:dev
Production build, then start:
npm -w server run build
npm -w server run start:prod
The server listens on port 3000 by default.
Client
Development (Vite dev server with HMR):
npm -w client run dev
The Vite dev server runs on http://localhost:5173. It has no API proxy: the client calls VITE_API_URL (default /api/v1 on its own origin), and the server allows CORS from http://localhost:5173. So point it at a running server:
npm -w client run dev:compose-api # API of the compose container (localhost:13000)
VITE_API_URL=http://localhost:3000/api/v1 npm -w client run dev # API of a locally started server
Production build:
npm -w client run build
The built files are emitted to client/dist/.
Running tests
Server (Jest)
npm -w server run test
Run a single spec file:
npm -w server run test -- --no-coverage test/scenario.controller.spec.ts
Watch mode:
npm -w server run test:watch
Print the NestJS logs of the test app (they're silenced by default; DEBUG=test):
npm -w server run test:debug
Client (Vitest + Storybook)
Storybook interaction tests (runs all *.stories.tsx files):
npm -w client run test:storybook
Launch Storybook dev server (with live preview):
npm -w client run storybook
Formatting code
Both workspaces use Prettier.
Server — rewrites src/**/*.ts and test/**/*.ts:
npm -w server run format
Client — rewrites src/**/*.{ts,tsx} and .storybook/**/*.{ts,tsx}:
npm -w client run format
Linting
Both workspaces use ESLint with typescript-eslint. The client also includes eslint-plugin-react-hooks and eslint-plugin-react-refresh.
Server:
npm -w server run lint # report issues
npm -w server run lint:fix # report and auto-fix
Client:
npm -w client run lint # report issues
npm -w client run lint:fix # report and auto-fix
Both workspaces target zero errors. Run lint before committing.
Building the container
The root Dockerfile builds a single image with the whole application: it builds the client and the server in separate stages, and the runtime image runs the server, which also serves the built client (CLIENT_DIR).
The runtime image uses Playwright's headless-only Chromium build (chromium-headless-shell) with just the shared libraries it links against, plus DejaVu and Liberation fonts (Liberation is metric-compatible with Arial/Times, so pages lay out as they would with those fonts). All browser launches are headless, so the full desktop Chromium isn't installed. If a new Playwright version needs another library, ldd on the chrome-headless-shell binary in the image lists what's missing.
docker compose build
To rebuild without the layer cache:
docker compose build --no-cache
Running with Docker Compose
Start (detached):
docker compose up -d
Build and start in one step:
docker compose up -d --build
Everything is served by the single liqa container at http://localhost:13000: the UI at /, the REST API at /api/v1, MCP at /mcp, Swagger at /docs and health at /health. Unknown paths outside those routes get the client's index.html, so client-side routes survive a page refresh.
When switching from the old two-container setup (server + client), remove the old containers with docker compose up -d --build --remove-orphans.
The SQLite database and stored files are persisted in ./data/, which is volume-mounted into the container.
Stop and remove containers:
docker compose down
View logs:
docker compose logs -f
Client overview
The client (client/) is a React 19 + TypeScript SPA built with Vite. It provides a browser UI for managing scenarios, runs, snippets, credentials, environments and sessions, and for importing exported YAML.
Tech stack
| Library | Purpose |
|---|---|
| React 19 + TypeScript | UI framework |
| Vite 6 | Dev server and bundler |
react-router-dom 7 (BrowserRouter) |
Client-side routing |
| @tanstack/react-query | Data fetching (cross-scenario runs list) |
| i18next + react-i18next | Internationalisation |
| lucide-react | Icon library |
| @monaco-editor/react | Code editor for steps and snippets |
| react-markdown + highlight.js | Markdown descriptions and code highlighting |
| yaml | YAML export of entities |
| moment | Relative timestamp formatting |
| ESLint 10 + Prettier | Linting and formatting |
| Storybook 10 + Vitest | Component development and testing |
Directory layout
client/
src/
api/ API client (client.ts) and types (types.ts)
components/ modals/ - run, export, export logs and delete confirmation modals
hooks/ useTheme, usePageTitle, useRunDefaults, useImportFile
i18n/ i18next bootstrap + locales/en.json
lib/ highlight.js setup, API error toast events
pages/ scenario/, run/, snippet/, credential/, environment/, session/, import/
ui/ Reusable component library (Badge, Button, Card, CodeEditor, Modal,
Select, SidePanel, Table, Toast, ... - see ui/index.ts)
.storybook/
stories/ *.stories.tsx for ui/ components
Routing
BrowserRouter with plain paths. The root and unknown paths redirect to /scenarios. The server answers these paths with the client's index.html (see architecture.md), so they work on refresh.
| Route | Page |
|---|---|
/scenarios |
Scenario list |
/scenarios/:id |
Scenario details (steps, versions, credentials, used snippets, files) |
/scenarios/:id/runs, /scenarios/:id/runs/:runId |
Runs of a scenario, run details |
/runs |
Cross-scenario runs list |
/snippets, /credentials, /environments, /sessions |
Entity lists (plus /:id, /new, /:id/edit where applicable) |
/import |
Central import |
Theming
Light/dark theme is toggled by the ThemeSwitcher button in the sidebar footer. The selection is persisted to localStorage and applied as data-theme on <html> before React mounts (anti-FOUC inline script in index.html).
The sidebar footer also shows the app version read from the workspace root package.json and injected via Vite define.