Operations Engine¶
Status: Draft for review
Purpose¶
Own cross-cutting runtime operations: asynchronous job execution, scheduling, audit log, observability, operational health, imports/exports, retry/dead-letter tooling and administrative diagnostics.
Owns¶
- Job/worker infrastructure contracts
- Scheduler orchestration
- Audit records
- Operational health/status
- Retry/dead-letter workflows
- Import/export orchestration
- Correlation IDs and observability context
- Operational notifications/incidents metadata
Non-goals¶
It does not own the business truth being processed by jobs. A job invokes the owning engine rather than mutating another engine's tables directly.
API contract — functional surface¶
These are contract-level resources and operations, not final controller/file names.
| Method | Route | Primary actor | Contract intent |
|---|---|---|---|
| GET | /api/platform/v1/operations/health |
Platform Ops | Read platform component health. |
| GET | /api/platform/v1/operations/jobs/failed |
Platform Ops | Inspect failed/dead-letter jobs. |
| POST | /api/platform/v1/operations/jobs/{id}/retry |
Platform Ops | Retry eligible failed job. |
| GET | /api/platform/v1/audit |
Platform Admin/Support | Search platform audit records under authorization. |
| GET | /api/tenant/v1/audit |
Tenant Owner/Admin | Search tenant-visible audit trail. |
| POST | /api/tenant/v1/imports |
Tenant Admin/Manager | Start validated import. |
| GET | /api/tenant/v1/imports/{id} |
Tenant Admin/Manager | Read import validation/progress/result. |
| POST | /api/tenant/v1/exports |
Tenant Admin/Manager | Request approved export. |
All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.
Events¶
job.failedjob.dead_letteredimport.completedimport.failedexport.completedincident.openedincident.resolved
Roles & responsibility matrix¶
Legend: A accountable, R responsible, C consulted, I informed, — none.
| Capability | Platform Admin | Tenant Owner | Tenant Admin | Specialist/Manager | Customer/Visitor |
|---|---|---|---|---|---|
| Platform runtime operations | A/R | I | I | C | — |
| Tenant audit review | I | A | R | C | — |
| Tenant import/export | I | A | R | R | — |
| Incident communication | A/R | I | I | I | I |
Dependencies¶
- All engines emit auditable facts/jobs/events
- Platform Engine for authorization/tenant identity
- Integration Engine for delivery/provider failures
Internationalization Contract¶
- Translation assistance/import/export jobs use the same tenant isolation, retries, idempotency, tracing and audit requirements as other async work.
- Logs/events retain locale identifiers where operationally relevant but should use stable machine error/status codes rather than localized log semantics.
- Monitoring should expose translation-job/provider failures independently from content publication.
Security / isolation requirements¶
- Jobs are tenant-context aware and idempotent.
- Audit records are append-oriented and access controlled.
- Operational tooling cannot become an unguarded path to mutate tenant data.
Acceptance criteria¶
- Email/order/integration jobs from Laravel have explicit target jobs.
- Workers can restart without losing durable work.
- Failed external calls are visible and retryable.
- Imports validate complete input before unsafe partial mutation where feasible.