Files
liqa/docs/architecture.md
T
agent 9bdba32a34 docs(auth): document optional authentication setup
- Explain opt-in configuration, protected surfaces, migrations and cookie behavior.
- Document operator CLI, MCP bearer use, cleanup, and supported local origins.
2026-11-09 15:50:12 -05:00

9.6 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    │
│          /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 for running it.

Optional authentication boundary

Account authentication is off unless AUTH_ENABLED=true. When enabled, the global guard protects REST and MCP controller routes and the run-events stream. The public routes are GET /health, GET /healthz, GET /manifest.json and POST /api/v1/auth/login; the manifest reports the auth-enabled flag so the client can choose its login flow. UI assets and the Swagger UI remain reachable, but API operations require authentication. Protected requests accept a bearer token or the AUTH_COOKIE_NAME cookie (liqa_auth by default). Browser login sets an HttpOnly, SameSite=Strict cookie and logout revokes the presented token and expires the cookie; HTTPS requests also get the Secure attribute. See development.md for operator setup and lifecycle details.

The authentication service stores users and hashed revoked-token identifiers in SQLite. Revocation records are retained through token expiry, then removed at startup and by the AUTH_REVOKED_TOKEN_CLEANUP_CRON job (0 3 * * * by default); no cleanup job is registered while auth is disabled. Authentication checks that the token is not revoked and that its account still exists, so deleting an account invalidates its outstanding tokens at the next request.

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. 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 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, the browser notifications toggle 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.

Run notifications: RunEventsService (scenario/) is an in-process rxjs subject. The scheduler emits run.started and run.finished (once per run, from the run's single exit points rather than each pass/fail transition), and GET /api/v1/scenarios/runs/events streams them as SSE. The useRunNotifications hook opens an EventSource to it, only while the user has enabled notifications and the browser permission is granted, and shows a Notification per event. See scenario.md.

See development.md for the full client tech stack and directory layout.