# Platform overview

The technical mental model for projects, workers, orchestration, and boundaries.

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](/docs/automation-sdk#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:

1. Workspaces contain projects.
2. Projects contain jobs, variables, queues, triggers, runs, jobs, and API keys.
3. API keys are project-scoped and cannot cross into another project.
4. 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

See the diagram or table on the linked documentation page.

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

**Static frontend contract**

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](/docs/automation-sdk#monitoring-contract) to observe existing external work without replacing its execution owner.
- Use [Playwright Jobs](/docs/playwright-jobs) when deliberately choosing worker-dispatched execution.
- Use [Runtime Variables](/docs/runtime-variables) to pass project-specific values into runs.
- Use [API Keys and Scopes](/docs/api-keys-scopes) before giving external systems access.
- Use [Efficient agent tools](/docs/agent-tools) for version-aware discovery, compact selection, safe batch planning and readiness verification.
- Use the separate [API Reference](/docs/api) for endpoint paths, request schemas, and try-it tooling.
