> ## Documentation Index
> Fetch the complete documentation index at: https://docs.energy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Operator Console

> Live events, runtime configuration and start/stop — served by the service itself

The bridge ships a built-in operator console at **`/console`** — a single
page served by the service itself, no separate frontend deployment. Open
it, paste the **process API key** once (stored in the browser), and connect.

## What it does today

<CardGroup cols={2}>
  <Card title="Live event stream" icon="tower-broadcast">
    Every pipeline action — forecast received, positions aggregated, CSV
    published, schedules submitted, orchestration errors, config changes,
    start/stop — appears live via Server-Sent Events, with history on load.
  </Card>

  <Card title="Runtime configuration" icon="sliders">
    Change sFTP host/credentials, Engrate settings, home control area,
    active areas, EIC identifiers and more — validated, applied **without a
    restart**, persisted across restarts, secrets write-only.
  </Card>

  <Card title="Start / Stop" icon="power-off">
    Stop pauses the orchestrator (scheduled runs become no-ops); manual
    process steps stay available as an operator override. State survives
    restarts and is visible in the status pill.
  </Card>

  <Card title="Delivery-day overview" icon="table-list">
    Per-day pipeline state (aggregated / published / submitted), including
    whether a step is stale because newer input arrived.
  </Card>
</CardGroup>

## The console API

Everything the page does goes through JSON endpoints (scope: **process**),
so it can equally be scripted:

| Endpoint                                  | Purpose                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /v1/console/status`                  | State, version, key config facts                                                   |
| `POST /v1/console/start` / `stop`         | Resume / pause the orchestrator                                                    |
| `GET /v1/console/events?limit=&after_id=` | Event history                                                                      |
| `GET /v1/console/events/stream`           | Live SSE stream (accepts `api_key` query param — `EventSource` cannot set headers) |
| `GET /v1/console/config`                  | Effective config, secrets masked                                                   |
| `PUT /v1/console/config`                  | Partial update, validated against the settings schema                              |
| `GET /v1/console/delivery-days`           | Pipeline state per delivery day                                                    |

## How runtime config works

Console changes are kept as an **overlay on top of the environment
variables**, persisted to `runtime_config.json` in the audit directory (the
Azure Files share in production — so they survive restarts and
scale-to-zero). The config panel marks overridden fields with a `runtime`
badge. Environment variables remain the base; deleting the overlay file
reverts everything to env values.

API keys are deliberately **not** editable via the console — rotating them
stays an infrastructure operation.

## Events on disk

Events are appended to `events.jsonl` next to the audit trail — the stream
you see in the console is the same file, so it doubles as a permanent
operations log.

## Planned (not in this draft)

* Configurable communication channels (sFTP, AS4, e-mail, API push)
* Configurable order of pipeline steps
* Message / file format configuration