Appearance
Glossary and terminology
Canonical abbreviations and roles across the Helix ecosystem. Use these meanings when docs or chats use short forms.
| Abbr | Term |
|---|---|
| SA | Surface App |
| HEE / helix-ee | Helix Execute Engine — same product. Repo helix-ee, stack HelixEeStack. HTTP API (POST /v1/executions), Step Functions, one Fargate worker per start. Abbreviation HEE = repo name helix-ee. |
| IO | Integration Orchestrator |
| RV | Remote verifier (remoteVerifiers / RemoteVerifierBinding) |
| RA | Remote action (remoteActions / RemoteActionBinding) |
| JPS | helix-job-processors (wizard job APIs) |
Inside HEE (same product — shorthand)
| Term | Meaning |
|---|---|
| HEE API | HTTP surface (POST /v1/executions), auth, run store — api.ee… |
| HEE worker | One Fargate task per start (helix-execution-worker) |
| HEE Kernel | HelixExecuteEngine — TS orchestrator loop inside the worker (backend/utils/HelixExecuteEngine) |
| HEE-core | In-image shared verifier registry (VerifierRegistry) — not the whole Kernel |
HEE Kernel = HelixExecuteEngine class only. Not the Fargate worker, not the HTTP API, not HEE-core.
Ambiguities (read this first)
Same word can mean different things inside HEE or across repos. Wrong layer = wrong repo.
| Often confused | Means A | Means B | Rule |
|---|---|---|---|
| Helix | Whole ecosystem (Platform + Apps + IO + HEE + JPS) | — | “Helix” is not synonymous with Helix Platform |
| Helix Platform | helix-platform shell (iframe, catalog, logs) | The entire fleet | Platform does not run HEE or IO graphs |
| HEE / helix-ee | The Execute Engine product (repo + API + worker) | — | Use either name; not a different system |
| HEE API | HTTP + run lifecycle (api.ee…) | HEE Kernel | API schedules; Kernel runs the loop |
| HEE Kernel | HelixExecuteEngine class | HEE worker (Fargate task) | Kernel = orchestrator code inside the worker |
| HEE-core | In-image VerifierRegistry + shared verifiers | HEE Kernel or SA HTTP gates | Subsystem inside the Kernel image |
| Integration Orchestrator (IO) | orchestrator-platform workflows | HEE Kernel (orchestrator.ts) | IO = separate product |
| runId | HEE execution id (POST /v1/executions) | IO pipeline run id | Correlate via externalRef + callbackData |
| job | helix-job-processors resource (jobId) | HEE execution/run | HEE uses run; JPS uses job |
| execution / session | One HEE runId + one Fargate task | Generic English | “One execution” = one HEE session |
| Plugin / hee-plugin | PluginContributions in HEE image | Surface App (com.helix.*) | SA is never a plugin |
| Verifier on canvas | — (IO v1 has no verifier nodes) | HEE gates (in-engine or RV) | Map remoteVerifiers onto HEE create in a map node |
/v1/hee/verify | Surface App HTTP route | HEE’s own API (api.ee…) | HEE worker POSTs to SA; path says hee but host is the app |
| Progress SSE | GET /v1/executions/{runId}/events/stream on HEE | Platform Log Center SSE | Interactive catch-up; not terminal authority |
| Terminal completion | SQS / HTTPS callback on HEE create | SSE stream end | IO await-async uses callback, not SSE |
| Helix AppSync | Legacy monolith real-time | HEE event store | HEE workers do not publish to AppSync today |
| Callback | callback on HEE create (SQS + callbackData) | IO completion queue message | Downstream → caller-owned queue |
| Trigger | Starts new work (entrypoint, backfill, SA button) | HEE hook (inside running worker) | Triggers are outside; hooks are inside the worker |
| Calendar | Caller + IO per async unit (generic) | IO product code | Patch campaign loop is caller-owned, not an IO node |
| GitHub App | Shared identity (/helix/github-app/* SSM, Platform) | Patch GitHub OAuth | Different credentials |
Isolation check: Trivy / Patch campaigns / helixPatch payload → helix-apps. IO graph / await-async → orchestrator-platform. HEE Kernel (HelixExecuteEngine) or HEE-core → helix-ee repo. iframe, catalog, push → helix-platform.
Repositories and products
Helix Platform (helix-platform)
Desktop shell — PWA, Cognito (no self-sign-up), Package Center, Control Panel, Log Center, Web Push, POST /v1/notifications. Hosts Surface Apps in iframes. Owns shared SSM /helix/github-app/*.
Does not own product remediation logic, HEE plugins, or IO workflow graphs.
Helix Apps (helix-apps)
Monorepo for Surface Apps — each app has UI + API + optional domain HTTP for HEE (/v1/hee/verify, /v1/hee/actions). CDK: HelixAppsStack. Examples: Helix Patch (com.helix.patch), Helix Intake (com.helix.intake).
Surface App (SA)
A product installed from the catalog and opened inside Platform. Package id like com.helix.patch. Owns product UX, durable campaign/job state, and domain tools/gates over HTTP. Not an HEE plugin and not an IO canvas node.
Integration Orchestrator (orchestrator-platform, IO)
Workflow engine — entrypoints, canvas (map / adapter / choice / await-async), adapters to downstream HTTP APIs, caller-owned SQS completions. Stays generic — no product rules in IO code.
HEE / helix-ee
Helix Execute Engine — repo helix-ee, CDK HelixEeStack. POST /v1/executions, Step Functions, DynamoDB run store, one Fargate worker per start. Ships in-engine plugins (shared verifiers, hooks). Calls Surface Apps only via RV/RA bindings on create.
HEE and helix-ee are the same product (abbreviation vs repo name).
helix-job-processors (JPS)
Six wizard processor stacks (spec, design, ux, e2e, tasks, code-review). IO adapter + SQS completion — parallel to HEE, not HEE plugins.
helix-cdk (deprecated)
Legacy monolith (HelixStack). Do not add new product work there.
Execution vocabulary
Run / session
One HEE run (runId) = one POST …/start = one Fargate worker until terminal. IO often awaits one async unit per backfill item. The worker reasons over a workspace (cloned repos + uploaded artifacts), bounded lifetime (~hours).
Trigger vs hook
| Trigger | Hook | |
|---|---|---|
| Starts | New work from outside HEE | Nothing — runs inside an already-running HEE process |
| Examples | Platform action, SA button, IO entrypoint/backfill | PluginContributions lifecycle callbacks in the worker |
Workspace
Git repos + EE-uploaded JSON artifacts on disk inside the HEE container. RV calls may include presigned snapshot URLs.
externalRef
Caller-defined correlation string on HEE create (e.g. helix-patch:job-123). Used for progress polling and callbacks.
HEE plugins (hee-plugin)
In-engine TypeScript registered via @helix/app-sdk → PluginContributions inside the HEE image (@helix/app-contract).
Includes shared verifiers (eslint, conventional-commits), hooks, state validators. Baked at build time — not Surface Apps, not IO nodes.
Do not confuse with:
- Surface App (
com.helix.*in helix-apps) - Remote verifier (HTTP to SA)
Verifiers and gates
Verifier (generic)
Deterministic check that returns pass/fail (and optional fix prompt). Two deployment modes:
| Kind | Where | Abbr |
|---|---|---|
| Shared / in-engine verifier | HEE image, VerifierRegistry | — |
| Domain / remote verifier (RV) | Surface App HTTP | RV |
HEE gate / verifier phase
When HEE runs verifiers at a phase (executor, task_complete, run_complete). A blocking gate can stop or reprompt the session. RV gates call SA HTTP; shared gates run in-process.
Remote verifier (RV)
RemoteVerifierBinding on create → remoteVerifiers. HEE POSTs to SA baseUrl + path (e.g. Patch /v1/hee/verify). Response { ok, summary, fixPrompt? } → gate policy.
Question: “Is this good enough?” (e.g. Trivy closure).
Remote action (RA)
RemoteActionBinding on create → remoteActions. HEE POSTs to SA tool endpoint (e.g. Patch /v1/hee/actions). Response { ok, data } — tool output, not a lifecycle gate.
Question: “Do X” (scan, bump, open PR, notify).
| RV | RA | |
|---|---|---|
| Timing | Phase-driven | Brain-driven |
| Blocks session? | Can (verdict: blocking) | No |
Trivy and product scanners stay in SA — not in the HEE image for Patch flows.
IO vocabulary
Entrypoint
Live workflow binding — HTTP trigger starts one IO run from a published graph.
Backfill
POST …/entrypoints/{id}/backfill with items[] — many IO runs from one trigger (parallel or dependsOn). Common for multi-item remediation.
Adapter (IO)
Canvas node that calls a registered downstream HTTP API (HEE / helix-ee, helix-job-processors, …). Completion via caller-owned SQS.
Map node
JSONata transform from entry payload to adapter create body.
await-async
IO node that parks until a completion message arrives on the SQS queue.
Callback / completion queue
Downstream publishes terminal event to IO/caller queue with callbackData tying back to the IO run id.
Platform shell vocabulary
Package Center
UI to install Surface Apps from catalog URLs.
Catalog
apps…/repo/index.json — lists installable packages and entryUrl for iframes.
Log Center
Platform UI + POST /v1/logs; SA/HEE can POST structured lines.