How it works

5-минутное введение в архитектуру OPORA. Если вы только что подключили первого провайдера и не до конца понимаете, почему «оно работает» — это именно та страница.

Слои сверху-вниз

┌────────────────────────────────────────────────────────┐
│  You + your team                                       │
└────────────────────────────────────────────────────────┘
           │
           ↓  (web-UI / API)
┌────────────────────────────────────────────────────────┐
│  OPORA control plane                                    │
│                                                         │
│  ┌───────────┐  ┌───────────┐  ┌────────────────┐     │
│  │ Space     │  │ Agent     │  │ Process        │     │
│  │ (tenant)  │→→│ (worker)  │→→│ (workflow DAG) │     │
│  └───────────┘  └───────────┘  └────────────────┘     │
│                                      ↓ на runtime'е    │
│                               ┌────────────────┐       │
│                               │ Run (instance) │       │
│                               └────────────────┘       │
└────────────────────────────────────────────────────────┘
           │
           ↓  (HTTP / webhooks / SMTP / API)
┌────────────────────────────────────────────────────────┐
│  External providers                                    │
│  Bitrix24 · amoCRM · ЮKassa · 1С · Telegram · VK · ... │
└────────────────────────────────────────────────────────┘

Слова и что они значат

Space — это ваша tenant-изоляция. Один space = одна команда / одна компания. У space’а свои секреты, свои OAuth-подключения, свои агенты. Ничто между space’ами не пересекается. При регистрации OPORA создаёт вам первый space (см. first-login wizard).

Agent — это «сотрудник» в вашем space’е. У каждого агента:

• имя и goal (human-readable цель)
• роль (operations / sales / support / custom…)
• 1 процесс (workflow DAG)
• KPI’и, которые автосчитаются по его runs’ам
• optional limits: cost cap / working hours / rate limits

Process — DAG-граф из нод: trigger-нода → processing-ноды → output-нода. Версионируется через revisions (git-like: каждая правка — новая revision; deploy revision → она становится активной). Можно откатиться на предыдущую revision одной кнопкой.

Run — одно исполнение процесса на конкретном trigger’е: кто-то заполнил форму в Tilda → webhook прилетел → start run → run проходит через ноды → завершается (done / failed / cancelled).

Trace — детализированный лог всех событий внутри run’а: что пришло на trigger, что передалось между нодами, сколько занял каждый шаг, что LLM ответил, какой status-code вернул Bitrix24, сколько стоило в центах. /runs/<id> страница в UI — это trace viewer.

Жизненный цикл trigger → action

Возьмём пример: Tilda-форма → amoCRM-лид.

1. Подключение: вы создали agent + process в OPORA. Process содержит ноды:

   webhook.trigger → ai.classify → amocrm.lead.create

2. Publish: нажали Publish — OPORA сохранила текущую revision как deployment и выдала webhook-URL.
3. Tilda hookup: вы скопировали URL в настройки формы Tilda.
4. User fills the form: Tilda POST’ит payload на webhook-URL.
5. OPORA валидирует: webhook.trigger нода проверяет соответствие подписи (HMAC / query-token / без валидации — зависит от preset’а).
6. Run создаётся: OPORA материализует новый run, состояние queued. Вы уже видите его в /runs.
7. Scheduler подхватывает: backend scheduler берёт queued runs и отправляет в step-worker.
8. Step-by-step execution:
   • webhook.trigger → output = body формы
   • ai.classify → input = form body, output = "hot" / "warm" / "cold"
   • amocrm.lead.create → input = form body + classify label, output = amocrm lead_id
9. Trace пишется: каждый шаг сохраняет input + output + timing + cost (если есть). Видно в /runs/<id>/traces.
10. Run completes: финальный статус done. KPI обновляется (runs_today++, cost_today += ai.classify cost).

Всё это — в пределах 1-2 секунд для простого workflow’а. Долгие шаги (LLM-call + Bitrix-call + delay) разбиваются на отдельные фоновые шаги; run состояние running пока все не сойдутся.

Что НЕ делает OPORA

• Не хранит бизнес-данных. Ваши заказы, клиенты, сделки — в вашей CRM / 1С / DB. OPORA проводит данные между ними, но сама не репозиторий.
• Не проксирует платежи. ЮKassa / T-Kassa / ваш эквайринг общаются напрямую с клиентом; OPORA получает только metadata-события (succeeded / failed / refunded).
• Не контролирует ваши accounts. Ваш Bitrix / amoCRM / Google workspace живут где жили. OPORA ходит в них через вами же созданные integrations.

Что OPORA делает хорошо

• Orchestration: гарантированная доставка, retry-с-backoff’ом, idempotency (повторный webhook → один и тот же run, а не два).
• Observability: каждый шаг сохраняется trace’ом, ошибки летят в Sentry (если вы его настроили — см. deploy-runbook §12 в репо), KPI auto-computed.
• Human-in-the-loop: любой шаг можно гейтить approval’ом («не списывай > 10000₽ без подтверждения owner’а»).
• Governance: RBAC (owner / admin / member), soft-delete под 152-ФЗ, audit trail всех действий, рaeversion-based rollback.

Где читать дальше

• Agents & Processes — деталь по версионированию процессов и template-resolver’у
• Runs & Traces — lifecycle state-machine и retry policies
• Secrets — AES-256 encryption model + OAuth refresh