- replace synchronize with migrations, starting with a generated initial migration that adopts databases created by synchronize - apply pending migrations in the docker container before the server, and refuse to start the server while migrations are pending - share one entity list and data source between app, migration runner, typeorm cli and tests; tests run the real migrations - add migration:run, migration:show and migration:generate scripts and a test that fails when entities and migrations differ - exit with code 1 when startup fails - bump version to 1.20.0
7.0 KiB
Architecture
Browser (React SPA) MCP client (AI agent, IDE)
│ / and /api/v1 │ /mcp (Streamable HTTP)
└──────────────┬──────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ liqa container (:13000 → 3000) NestJS app, server/src/ │
│ │
│ Routes / built client (ServeStaticModule) │
│ /api/v1 REST API /docs Swagger UI │
│ /mcp MCP tools /health health check │
│ │
│ McpService MCP tools → services below │
│ ScenarioService scenarios, steps, versions, runs │
│ ScenarioSchedulerService @Interval(1 s) run worker │
│ E2eExportService standalone Playwright test zip │
│ SnippetService snippets + versions │
│ EnvironmentService environments │
│ CredentialService credentials │
│ ImportService central YAML import │
│ FileStorageService scenario files + run artifacts │
│ SessionService saved browser sessions │
│ SessionContextService live Playwright contexts │
│ SessionSchedulerService @Interval(60 s) session cleanup │
│ BrowserService ad-hoc open / exec │
│ CodeExecutorService runs step / snippet JS │
└───────────────┬─────────────────────────────┬───────────────┘
│ TypeORM (better-sqlite3) │ Playwright
▼ ▼
data/liqa.db, data/files/ chromium-headless-shell
Everything runs in one container built from the root Dockerfile: the server serves the API, MCP and Swagger, and also the built client. See development.md for running it.
Server components (server/src/)
- McpService (
mcp/) registers the MCP tools and delegates to the services below. Each request gets a fresh MCP server over the Streamable HTTP transport. - ScenarioService (
scenario/) manages scenarios, steps, credential aliases, versions, runs, run logs, scenario/run files, and scenario export/import. - ScenarioSchedulerService picks up pending runs every second (up to 10 in parallel) and executes their steps in order in one Playwright browser per run. It handles step and scenario timeouts, failure page dumps (screenshot + HTML), Playwright traces, and saving the browser as a session (
saveSession). - E2eExportService builds a standalone Playwright test project (zip) from a scenario, bundling the snippets, credentials and files it uses.
- SnippetService (
snippet/), EnvironmentService (environment/) and CredentialService (credential/) provide CRUD plus export/import. - ImportService (
import/) implementsPOST /import: validates a YAML stream of mixed items, then imports them in dependency order (environments, credentials, snippets, scenarios). - FileStorageService (
file/) stores uploaded scenario files and run artifacts underFILES_DIR, and deletes expired files on a cron schedule (FILE_CLEANUP_CRON). - SessionService (
session/) persists saved sessions (cookies, localStorage); SessionContextService keeps their live Playwright contexts; SessionSchedulerService closes idle sessions and deletes old closed ones every minute. - BrowserService (
browser/) handles ad-hoc automation (POST /api/v1/open,POST /api/v1/exec, and theopen_url/exec_codeMCP tools), optionally in a saved session. - CodeExecutorService (
code-executor/) checks step and snippet code with acorn, then runs it with thecontextAPI (page, environment values, credentials, snippets, files, assertions, logs). It is not a security sandbox: step code is trusted.
Cross-cutting pieces:
config/app.config.ts- all settings, validated at startup (see.env.example).database/- the entity list, TypeORM data source options (shared by the app, the migration runner and the TypeORM CLI), the migration runner and the migrations.common/app-package.ts- app name and version, read from the workspace rootpackage.json.common/client-static.ts- serving the built client, with theindex.htmlfallback for client-side routes.common/body-parsers.ts- YAML request bodies (application/yaml) for the import endpoint.interceptors/- a trace id per request (kept inAsyncLocalStorageand added to log lines) and request/response logging;filters/- consistent error responses.
Data
SQLite via TypeORM. The schema is managed by migrations (server/src/database/migrations/, registered in migrations/index.ts); synchronize is off. The Docker container applies pending migrations (node dist/database/migrate) before starting the server, and the server refuses to start while migrations are pending. See "Database migrations" in development.md. The main tables:
scenarios/scenario_stepshold the latest version of each scenario;scenario_versionsholds a snapshot of every version (content + steps).snippetsholds the latest version of each snippet;snippet_versionsholds every version. Step code pins a version withrunSnippet("alias@N").scenario_runsrecord the scenario version, environment, trace mode and status;scenario_run_stepskeep their own copy of each step's code, so a run always shows what it executed;scenario_run_logshold ordered run logs.files+scenario_files/scenario_run_filesmap stored files to scenarios and runs.environments,credentials,scenario_credentials(alias → credential per scenario),sessions.
See scenario.md for versioning, runs and import/export rules.
Client (client/)
A React 19 + TypeScript SPA. During development it's served by the Vite dev server; in the Docker image the server serves the built client from the same origin as the API.
The client calls the server REST endpoints directly — there is no separate BFF layer. Routing uses BrowserRouter; the server answers any GET outside /api, /mcp, /docs and /health with the client's index.html, so client-side routes survive a page refresh.
Pages: scenarios (with steps, versions, credentials, used snippets and files), runs, snippets, credentials, environments, sessions, and the central import page. The sidebar footer contains the theme switcher and the app version (injected from the workspace root package.json at build time).
See development.md for the full client tech stack and directory layout.