# 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 by the Vite dev server during development. In the Docker image the server serves the built client itself (`ServeStaticModule`, see `server/src/common/client-static.ts`), 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. The sidebar footer contains the theme switcher and the app version (injected from the workspace root `package.json` at build time). See [development.md](development.md) for the full client tech stack and directory layout.