Files
liqa/docs/architecture.md
ars9 718a12c2f4
CI / changes (pull_request) Successful in 6s
CI / version (pull_request) Skipped
CI / server (pull_request) Successful in 1m30s
CI / client (pull_request) Successful in 1m31s
CI / image (pull_request) Skipped
feat(logs): collapse large run log data and serve client manifest
- collapse run log data blocks whose pretty-printed JSON exceeds a byte
  or line limit, with a per-block toggle and an expand/collapse-all
  button next to the Logs heading
- align data blocks and toggles with the context/message column
- add a "Copy logs" button that copies the filtered logs as plain text
  with every data block expanded
- add GET /manifest.json with the app name, version and run log data
  limits (RUN_LOG_DATA_COLLAPSE_BYTES / RUN_LOG_DATA_COLLAPSE_LINES)
- load the manifest in the client stale-while-revalidate: localStorage
  copy first, refetched per page load and on tab focus after a while
- show the server version in the sidebar footer, with a reload hint
  when it differs from the client build

Closes #3
2026-10-02 14:05:49 +03:00

83 lines
7.8 KiB
Markdown

# 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 │
│ /manifest.json public client configuration │
│ │
│ 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](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/`) implements `POST /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 under `FILES_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 the `open_url` / `exec_code` MCP tools), optionally in a saved session.
- **CodeExecutorService** (`code-executor/`) checks step and snippet code with acorn, then runs it with the `context` API (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 root `package.json`.
- `common/client-static.ts` - serving the built client, with the `index.html` fallback for client-side routes.
- `common/body-parsers.ts` - YAML request bodies (`application/yaml`) for the import endpoint.
- `interceptors/` - a trace id per request (kept in `AsyncLocalStorage` and 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](development.md). The main tables:
- `scenarios` / `scenario_steps` hold the **latest** version of each scenario; `scenario_versions` holds a snapshot of every version (content + steps).
- `snippets` holds the latest version of each snippet; `snippet_versions` holds every version. Step code pins a version with `runSnippet("alias@N")`.
- `scenario_runs` record the scenario version, environment, trace mode and status; `scenario_run_steps` keep their own copy of each step's code, so a run always shows what it executed; `scenario_run_logs` hold ordered run logs.
- `files` + `scenario_files` / `scenario_run_files` map stored files to scenarios and runs.
- `environments`, `credentials`, `scenario_credentials` (alias → credential per scenario), `sessions`.
See [scenario.md](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`, `/health` and `/manifest.json` 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.
`GET /manifest.json` is the server's public configuration for the client: the app `name` and `version`, and settings the UI needs (currently `runLogs.dataLimits`, from `RUN_LOG_DATA_COLLAPSE_BYTES` / `RUN_LOG_DATA_COLLAPSE_LINES`). The client reads it through `client/src/lib/manifest.ts` and the `useManifest()` hook, stale-while-revalidate: the copy cached in `localStorage` (or built-in defaults on first visit) is used right away, and the manifest is refetched once per page load and when the tab becomes visible again after 5 minutes. The server sends it with `Cache-Control: no-cache` and an ETag, so an unchanged manifest costs a 304. Add new client-facing settings to the manifest (`server/src/manifest/`) rather than as build-time Vite variables.
See [development.md](development.md) for the full client tech stack and directory layout.