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

# Operations overview

> What running a Swiss HR Easy installation involves, and where the playbooks are.

Every customer runs their own Azure environment. Operating one means keeping that
environment healthy, its secrets fresh, its scheduled jobs running, and its data
recoverable.

## The environment

| Component                  | Purpose                                                |
| -------------------------- | ------------------------------------------------------ |
| Azure App Service          | The Next.js application, containerised.                |
| PostgreSQL Flexible Server | The database.                                          |
| Azure Blob Storage         | Documents, receipts, certificates, contracts.          |
| Azure Key Vault            | The field-encryption key and integration credentials.  |
| Application Insights       | Structured logs, traces, alerts.                       |
| LibreOffice sidecar        | DOCX to PDF conversion for contracts and certificates. |

Infrastructure is Terraform, with per-environment configurations and remote state.

## Scheduled jobs

Several capabilities depend on jobs firing on time. They are triggered by scheduled
workflows calling protected endpoints with a shared `CRON_SECRET`:

| Job                           | Effect if it stops                                           |
| ----------------------------- | ------------------------------------------------------------ |
| SECO Stellenmeldung sync      | Embargo states stop advancing; reporting drifts out of sync. |
| Applicant e-mail scan         | Inbound applications stop attaching to their applications.   |
| Onboarding document reminders | Missing documents stop being chased.                         |
| Probation questionnaires      | Automatic questionnaires stop dispatching.                   |
| BFS Gemeindeliste refresh     | Municipality reference data goes stale.                      |
| Database credential rotation  | Credentials age past policy.                                 |

The **AI-coach learning cycle** is the exception: it has no built-in schedule. An
operator with `system:configure` triggers it from the admin button, or you point your
own scheduler at its endpoint using `CRON_SECRET` as a bearer token.

<Note>
  Scheduled workflows run the copy of their file on the **default branch**, which is `develop`. A
  workflow change is live on the schedules as soon as it lands there.
</Note>

## Day-to-day

<CardGroup cols={2}>
  <Card title="Deployment" icon="rocket" href="/operations/deployment">
    The pipeline, environments, and how a release reaches production.
  </Card>

  <Card title="Environment variables" icon="gear" href="/operations/environment-variables">
    Every setting, what it does, and which belong in Key Vault.
  </Card>

  <Card title="Feature flags" icon="toggle-on" href="/operations/feature-flags">
    Switching modules off per installation.
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/operations/monitoring">
    Logs, correlation, alerts, and health checks.
  </Card>

  <Card title="Runbooks" icon="book" href="/operations/runbooks">
    Rollback, incidents, restore, secret rotation, customer onboarding.
  </Card>

  <Card title="The docs site" icon="file-lines" href="/operations/docs-site">
    Running and deploying this documentation, including the custom domain.
  </Card>
</CardGroup>

## Playbook conventions

The playbooks in `docs/operations/` follow two rules that make them usable at 03:00:

* Every playbook opens with a **"When you reach for this"** line, so on-call knows in
  one sentence whether they are in the right place.
* Every playbook ends with a **Verification** section. If you cannot tick every box, the
  procedure is not done.

They are deliberately customer-agnostic and use placeholders (`<app>`, `<rg>`,
`<vault>`). Per-customer resource inventories, contacts and decision logs live in a
customer overlay under `docs/customers/<customer>/`.

## Keeping the playbooks true

Update the relevant playbook **in the same PR** as any production change that affects
operations. A playbook that describes last quarter's infrastructure is worse than no
playbook, because it is trusted.