Documentation

Core Concepts

Fundamental building blocks of the OpsOrch platform.

1. Unified API Layer

OpsOrch exposes unified REST APIs for incidents, alerts, logs, metrics, tickets, messaging, services, teams, deployments, and orchestration. Instead of typical GET list endpoints, OpsOrch uses a powerful POST .../query pattern for all collections to support complex filtering.

Normalized Resource

Regardless of the backend (PagerDuty, OpsGenie, etc.), an incident always looks like this:

json

{
  "id": "inc-123",
  "title": "Database connection timeout",
  "status": "TRIGGERED",
  "severity": "HIGH",
  "service": { "id": "payment-api" },
  "providerMetadata": {
     "source": "pagerduty",
     "externalId": "P12345",
     "url": "https://pagerduty.com/..."
  }
}

This normalization allows building generic UI components and automation logic that survive vendor migrations.

2. Adapter Architecture

OpsOrch Core contains no provider-specific logic. It defines Interfaces (Contracts) that Adapters implement. This dependency inversion is what makes OpsOrch vendor-agnostic.

OpsOrch Core

Defines Interface

interface IncidentProvider

Calls ->

↓

Adapter

Implements Logic

func Query()

Req ->

↓

Vendor API

External System

GET /incidents

3. QueryScope

Instead of learning JQL, PromQL, and Lucene simultaneously, you use a sharedQueryScopeobject. Adapters translate this generic intent into native query languages.

Generic Intent

json

// What the UI or API Client sends:
{
  "service": ["payment-api"],
  "environment": "production",
  "limit": 10
}

Jira Adapter Translation

project = OPS AND text ~ "payment-api" AND env = "prod"

Datadog Adapter Translation

service:payment-api env:production

4. Structured Queries

For advanced filtering where a simple scope isn’t enough, OpsOrch uses a recursive logic expression structure. This enables building powerful visual query builders that work across all providers.

json

{
  "operator": "AND",
  "filters": [
    { 
       "field": "severity", 
       "operator": "EQ", 
       "value": "error" 
    },
    { 
       "field": "message", 
       "operator": "CONTAINS", 
       "value": "timeout" 
    }
  ]
}

5. Provider Deep Links

Normalized resources can carry optional url fields that point back to the source system. OpsOrch passes these through without modification so operators can jump directly to the vendor UI for details.

json

{
  "id": "alert-891",
  "title": "High error rate",
  "status": "open",
  "severity": "critical",
  "url": "https://datadog.com/monitors/123"
}

6. Orchestration: Plans and Runs

Runbooks and workflows are treated as first-class operational data. OpsOrch exposes plans (templates) and runs (live executions), allowing clients to launch runs and complete manual steps without talking directly to the upstream system.

json

{
  "id": "release-checklist",
  "name": "Release Checklist",
  "steps": [
    { "id": "verify", "type": "verify", "title": "Check error budget" },
    { "id": "approve", "type": "manual", "title": "Ops approval" }
  ]
}