Platform overview
The technical mental model for projects, workers, orchestration, and boundaries.
On this page
BernOps adds lightweight, project-scoped monitoring to existing automations without replacing their executor. Your scheduler, CI system, service or script retains commands, startup, retries, signals and business results. See the external monitoring contract, including the current SDK startup limitation.
BernOps also offers separately selected worker execution, queues, triggers and coding-agent capabilities. Those execution modes are not prerequisites for monitoring external work. A project represents one application or operational surface, and each job, reporting run, trigger, queue, API key and variable stays within that project boundary.
Mental model
The product has three planes; the execution plane below applies to jobs deliberately dispatched to BernOps workers, not to externally observed automations:
| Plane | What it does | Primary code path |
|---|---|---|
| Control plane | Browser UI for workspaces, projects, jobs, queues, variables, runs, and keys. | frontend |
| Orchestration plane | Go REST API, auth checks, run dispatch, WebSocket worker gateway, database writes. | backend |
| Execution plane | Node worker that receives run payloads and starts Playwright. | worker |
The frontend is a static Next application. It does not own API routes. Browser code calls the Go backend through lib/api-client.ts, and authentication is handled by Supabase PKCE in the browser.
Resource hierarchy
The hierarchy is intentionally narrow:
- Workspaces contain projects.
- Projects contain jobs, variables, queues, triggers, runs, jobs, and API keys.
- API keys are project-scoped and cannot cross into another project.
- Worker execution is assigned per run, not per project.
Project-management API calls use a project/resource ID and appropriately scoped credential. External SDK reporting instead uses the approved HTTPS origin, external-job ID and job-bound writer; it needs no BernOps worker or transfer of process ownership.
Run execution path
Run request
A user, API key, trigger, or saved job starts an execution.
Dispatch
The backend records the run and claims one connected worker.
Temp workspace
The worker writes test files and a generated Playwright config.
Telemetry
Logs, steps, traces, screenshots, and results stream back to BernOps.
For a worker-dispatched run, the backend creates a test_executions row, resolves project runtime variables, picks an available worker, and sends a run_tests WebSocket message. The worker writes the provided Playwright files into a temporary directory, generates a Playwright config, and starts npx playwright test.
Results are streamed back as structured logs and steps. The backend persists them so the run detail page can show timeline events, console output, network data, screenshots, attachments, and final status.
External automation takes a different path: its existing executor runs the work, while approved observations enter the reporting API and are persisted/shown in BernOps. Starting a reporting record does not dispatch a worker, grant cancellation/retry authority or prove business health.
Auth principals
BernOps recognizes two caller types:
| Principal | Best for | Notes |
|---|---|---|
| User JWT | Browser-authenticated management actions. | Inherits the signed-in user's workspace/project role. |
| Project API key | CI, external runners, queue workers, saved-job execution, ingest. | Bound to one project and limited by scopes. |
Use a user JWT for admin actions like creating projects and managing keys. Use a project API key when a machine or external system needs repeatable access.
Technical boundaries
The frontend is deployed as a static export. Do not expect frontend routes to run server code, read cookies on the server, or expose app/api handlers. Runtime behavior should go through the Go backend.
The backend routing source of truth is backend/main.go. Worker protocol payloads are mirrored between backend/protocol and worker/src/protocol/types.ts; when fields change, both sides must stay in sync.
Where to go next
- Use Automation SDK to observe existing external work without replacing its execution owner.
- Use Playwright Jobs when deliberately choosing worker-dispatched execution.
- Use Runtime Variables to pass project-specific values into runs.
- Use API Keys and Scopes before giving external systems access.
- Use Efficient agent tools for version-aware discovery, compact selection, safe batch planning and readiness verification.
- Use the separate API Reference for endpoint paths, request schemas, and try-it tooling.