liqa/docs/architecture.md

Architecture

┌──────────────────────────────────────────────────────┐
│ Browser (React SPA - client/)                       │
│                                                      │
│ Environments  Credentials  Snippets                 │
│ Sessions      Scenarios    Runs                     │
└─────────────────────────────┬────────────────────────┘
                              │ HTTP REST (:13000)
                              │
MCP client (AI agent / VS Code Copilot)
        │  HTTP /mcp (Streamable MCP)
        ▼
┌──────────────────────────────────────────────────────┐
│ NestJS app (server/src/)                            │
│                                                      │
│ McpService                all MCP tools             │
│ SessionService            session persistence        │
│ SessionContextService     live browser contexts      │
│ EnvironmentService        environment CRUD + import  │
│ CredentialService         credential CRUD + import   │
│ SnippetService            snippet CRUD + import      │
│ BrowserService            ad-hoc open/exec           │
│ CodeExecutorService       sandboxed JS runtime       │
│ ScenarioService           scenarios/steps/runs CRUD  │
│ ScenarioSchedulerService  @Interval(1 s) run worker  │
└───────────────────────┬──────────────────────────────┘
                        │ better-sqlite3 (TypeORM)
                        ▼
                 data/sessions.db

• McpService registers MCP tools and delegates to session, environment, browser, and scenario services.
• SessionService persists session records in SQLite. SessionContextService manages live Playwright contexts for open sessions.
• EnvironmentService, CredentialService, and SnippetService provide CRUD plus import/export upserts.
• BrowserService handles stateless ad-hoc automation (/open, /exec) and session-aware browsing.
• CodeExecutorService validates and executes user JS with page, context, and helper APIs.
• ScenarioService manages scenarios, steps, credential aliases, runs, logs, and scenario import/export.
• ScenarioSchedulerService polls pending runs every second and executes step runs to completion.

Client (client/)

A React 19 + TypeScript SPA served separately by Vite during development. In Docker Compose the same build artefacts are served statically alongside the API.

The client calls the server REST endpoints directly — there is no separate BFF layer. Routing uses HashRouter so the Vite proxy and server-side routes are never ambiguous.

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.