Helix developer guide — stack, local work, deploy, contribute

How the Helix sibling repos fit together, how to run them day-to-day, and how to contribute without breaking isolation.

Canonical architecture: Architecture.

1. The stack at a glance

Layer	Repo	What you change	Talks to
Desktop shell	helix-platform	PWA, Package Center, Log Center, Cognito shell; owns `/helix/github-app/*` SSM	Catalog HTTPS, iframe apps
Surface Apps	helix-apps	Patch, Intake, … UI + app APIs + domain verifiers	Platform iframe, IO HTTP, optionally helix-ee
Orchestration	orchestrator-platform	Adapters (code) or workflow graphs (no code — canvas)	helix-ee / job-processors HTTP + SQS completion
Execute Engine	helix-ee	Job API, HEE worker, `@helix/app-contract` / remote verifiers	GitHub App SSM, S3 workspaces, Bedrock
Wizard processors	helix-job-processors	Spec/design/ux/e2e/tasks/code-review job APIs	Same pattern as helix-ee (isolated Fargate per job)

Deprecated: helix-cdk (HelixStack). Do not land new product work there.

Products talk over HTTPS and SQS only — no shared Node process, no importing another product’s Lambda code.

text

  Developer laptop                    AWS account 917630709045 (dev)
  ─────────────────                   ─────────────────────────────
  Platform FE (Vite)  ──────────────► api.platform… / Cognito
  Patch FE+API (Vite+Express) ──────► (local API) and/or api.apps…
  Intake FE (Vite) ─────────────────► Intake API (:8788 or api.apps…/v1/intake)
                                      │  helix-flowgraph CLI --local
  IO Admin FE (optional) ───────────► api.orchestrator… + AppSync
                                      │
                                      ▼
                               IO workflow (S3) ──► helix-ee / processors
                                                      │
                                                      ▼
                                                   Fargate HEE

2. Recommended working model

Most of the stack is cloud-backed. The productive pattern for the team:

Role	Local	Point at
Platform UI	`frontend` Vite	Deployed Platform API + Cognito (`platform.helix-dev…`)
Surface App UI/API	App Vite + local Express (Patch)	Local backend; call deployed IO + helix-ee with M2M secrets
helix-ee engine / API	Unit tests + occasional full `deploy:dev`	Deployed API `api.ee.helix-dev…` for integration
IO workflow editing	No local IO required	Hosted Admin UI: `https://orchestrator.igentify.in`
IO adapter code	Unit tests in `packages/config-engine`	Deploy IO stack when shipping adapter changes

Do not try to run Platform + Apps + IO + helix-ee Fargate all as local processes for a single feature. Prefer local FE / app API + shared dev cloud for everything long-running (SFN, Fargate, Cognito M2M, SQS).

Shared credentials already in the account:

GitHub App SSM: /helix/github-app/* (owned by Helix Platform)
helix-ee M2M: Secrets Manager helix-ee/oauth-m2m
Patch OAuth / IO M2M: helix-apps/patch/* secrets (see Patch README)

AWS profile for this account: 917630709045_AdministratorAccess (region us-east-1).

bash

aws sso login --profile 917630709045_AdministratorAccess

3. Local development by area

3.1 Helix Platform (shell)

bash

cd helix-platform
cp .env.dev.local.example .env.dev.local   # only needed for CDK deploy
npm install

# Frontend against hosted API
# frontend/.env.local
#   VITE_BASE_DOMAIN=platform.helix-dev.igentify.in

cd frontend && npm run dev

Login: Cognito users are admin-created (no self-sign-up). Ask for a platform-admins or normal user in the Platform pool.
Package Center: add source https://apps.helix-dev.igentify.in/repo/index.json to install Patch / Intake.
Backend Lambdas: change in backend/, then npm run deploy:dev — there is no long-lived local API server for Platform today.

3.2 Helix Apps (Patch, Intake)

bash

cd helix-apps
npm install

# Patch — full local FE + API
cp apps/patch/.env.example apps/patch/backend/.env.local
# Fill GitHub / orchestrator / helix-ee settings as needed (see apps/patch/README.md)
npm run dev:patch
# UI http://localhost:5190  API http://localhost:8787

# Intake — FE + API (helix-flowgraph CLI)
npm run dev:intake
# UI http://localhost:5191  API http://localhost:8788

Patch tips

Prefer pointing OAuth / IO / helix-ee at dev cloud endpoints from .env.local rather than mocking them.
Domain verify (POST /v1/hee/verify) is called by helix-ee in the cloud; for that path you need a reachable Patch API (PATCH_PUBLIC_API_BASE) or test verify handlers with unit tests locally.
Catalog for Package Center is repo/index.json (deployed with HelixAppsStack).

3.3 helix-ee

bash

cd helix-ee
cp .env.dev.local.example .env.dev.local
npm install
npm test          # packages / engine unit tests as documented in-repo
npm run deploy:dev   # ships API + SFN + Fargate image (needs Docker + CodeArtifact)

Day-to-day engine work:

Change HEE / packages/app-contract / remote verifiers.
Run unit tests.
Deploy to the shared HelixEeStack when you need a live execution.
Call the API with Cognito M2M (see helix-ee README) or @helix-ee/sdk.

There is no supported “full HEE Fargate on localhost” path. Use the deployed worker.

Clients (Patch, IO) should keep using https://api.ee.helix-dev.igentify.in unless you intentionally deploy a personal stack (not the default).

3.4 Integration Orchestrator — edit workflows (no code)

This is the path for “change how Helix Patch / helix-ee are wired” without opening a PR:

Open https://orchestrator.igentify.in (dev Admin UI).
Sign in with Cognito (request access if needed).
Open the customer (e.g. Helix Patch customer) → Draft workflow (only drafts are editable).
Edit the canvas: map nodes, helix-ee / helix-job-processors adapters, await-async, JSONata mappings.
Simulate / inspect runs from the UI (same executor as production entrypoints).
Promote when ready (draft → active).

Helix-specific mapping notes: orchestrator-platform docs/HELIX_ADAPTERS.md (e.g. payload.helixPatch.heeRemoteVerifiers → helix-ee remoteVerifiers).

Do not put Patch/Trivy product rules or HEE plugin registries into IO nodes. IO only orchestrates.

Optional local Admin UI (still talks to deployed API):

bash

cd orchestrator-platform
# frontend/.env.local
#   VITE_BASE_DOMAIN=orchestrator.igentify.in
cd frontend && npm run dev

Prefer the hosted UI unless you are changing Admin frontend code.

3.5 Integration Orchestrator — adapter / runtime code

bash

cd orchestrator-platform
cp .env.dev.local.example .env.dev.local
npm install
# unit tests in packages/config-engine
AWS_PROFILE=917630709045_AdministratorAccess npm run deploy:dev

Only needed when changing adapter TypeScript, executor behavior, or infra — not for normal workflow canvas edits.

3.6 helix-job-processors

Same pattern as helix-ee: unit tests locally, deploy:dev for live APIs. Documented in that repo’s docs/. Most Surface App / Patch flows use helix-ee; processors matter for wizard-style jobs.

4. Deployment options

Option	When	How
Shared dev stacks (default)	Daily integration	Each repo `npm run deploy:dev` → known domains above
Local FE only	UI iteration	Vite → hosted APIs
Local Surface App API	Patch/Intake API work	Express on laptop; cloud IO/EE
Workflow-only	Mapping / graph changes	IO Admin UI; no deploy
Personal AWS stack	Rare isolation experiments	New CDK prefix/account — avoid unless DevOps agrees (DNS, Cognito, cost)

Deploy commands (dev account)

bash

# Platform
cd helix-platform && AWS_PROFILE=917630709045_AdministratorAccess npm run deploy:dev

# Apps (Patch API + catalog + Intake static)
cd helix-apps && AWS_PROFILE=917630709045_AdministratorAccess npm run deploy:dev

# helix-ee (API + Fargate image — Docker required)
cd helix-ee && AWS_PROFILE=917630709045_AdministratorAccess npm run deploy:dev

# IO (only if shipping adapter/infra code)
cd orchestrator-platform && AWS_PROFILE=917630709045_AdministratorAccess npm run deploy:dev

Before Docker/npm installs that hit igentify CodeArtifact:

bash

aws sso login --profile 917630709045_AdministratorAccess
# refresh ~/.npmrc token / ECR login as in each repo’s README when builds fail on auth

Dev domains (cheat sheet)

Service	URL
Platform	https://platform.helix-dev.igentify.in
Platform API	https://api.platform.helix-dev.igentify.in
Apps catalog	https://apps.helix-dev.igentify.in/repo/index.json
Patch	https://apps.helix-dev.igentify.in/apps/patch/
Intake	https://apps.helix-dev.igentify.in/apps/intake/
Apps API	https://api.apps.helix-dev.igentify.in
helix-ee API	https://api.ee.helix-dev.igentify.in
IO Admin	https://orchestrator.igentify.in
IO API	https://api.orchestrator.igentify.in

5. Contribution best practices

Isolation (non-negotiable)

Surface Apps own product UX and domain verifiers (e.g. Trivy rescan). They must not import HEE plugin registries or hard-code IO node ids in the engine.
helix-ee knows job + workspace (+ remote HTTP verifiers by binding). It must not call Platform or Patch by product name except via binding URLs in remoteVerifiers.
IO owns graphs and adapters. Put product policy in the app or in HEE shared verifiers — not as one-off IO “Trivy nodes”.
Platform hosts iframes and catalog; it does not embed Patch/HEE business logic.

See the isolation table in ARCHITECTURE.md.

Git / PR hygiene

Default branch for PRs: current on each Helix sibling repo.
No slashes in branch names (CI embeds branch in Docker/ECR tags). Use feature-remote-verify, not feature/remote-verify.
Conventional commits / PR titles where the repo’s CI requires them (feat:, fix:, docs:, …).
One concern per PR when possible (contract vs app UI vs IO docs).

Contracts and versions

@helix/app-contract / @helix/app-sdk SoT: helix-ee packages/. Publish via the repo’s publish script when consumers need a new version on CodeArtifact.
Prefer extending RemoteVerifierBinding / OpenAPI over ad-hoc env flags between apps and EE.
IO Helix wiring that is “just mapping” → update workflow canvas + document in HELIX_ADAPTERS.md; avoid adapter TypeScript unless the HTTP contract itself changes.

Secrets and config

Never commit .env.dev.local, PEMs, or Cognito client secrets.
GitHub App identity is shared SSM under Platform — do not recreate /helix/github-app/* in helix-apps or helix-ee stacks.
App-specific secrets stay under helix-apps/<app>/… or helix-ee/….

Testing before you ask for review

Change	Minimum bar
Platform FE	`npm run lint` / build; smoke login against dev
Surface App	Unit tests for verify/API; local `dev:patch` smoke
helix-ee	Package/engine unit tests; deploy + one create/start smoke if API changed
IO workflow only	Simulate in Admin UI; attach run id in the PR/ticket
IO adapter code	config-engine tests + deploy:dev

Who to involve

Topic	Typical owner
Package Center / shell UX	Platform
Patch / Intake product	helix-apps
Execution semantics / verifiers in-engine	helix-ee
Canvas mapping / promote	whoever owns the customer workflow (often app team + light DevOps)
DNS, Cognito pools, CodeArtifact trust	DevOps (DPS)

6. Example team scenarios

A. “I only change Patch UI”
Local npm run dev:patch → PR in helix-apps → deploy HelixAppsStack when merging to current.

B. “I need helix-ee to call Patch verify”
Contract + bridge in helix-ee; Patch /v1/hee/verify; IO map heeRemoteVerifiers on the canvas (docs in HELIX_ADAPTERS). Deploy EE + Apps; promote IO draft.

C. “I only retarget the Patch remediation workflow”
No code. Edit draft on https://orchestrator.igentify.in → simulate → promote.

D. “I change Platform Package Center”
Local Platform FE against hosted API → PR helix-platform → deploy:dev.

E. “I’m onboarding”
Read Architecture → get Cognito users for Platform + IO → install Patch from Package Center → run one Patch scan against a test repo → open a draft IO workflow read-only to see helix-ee nodes.

Doc	Location
Glossary / terminology	Glossary
Architecture + mermaid	Architecture
Platform contribute	CONTRIBUTING.md · AGENTS.md
Apps contribute / anti-patterns	helix-apps `CONTRIBUTING.md` · AGENTS.md
helix-ee contribute	helix-ee `CONTRIBUTING.md` · AGENTS.md
IO contribute (canvas vs code)	orchestrator-platform `CONTRIBUTING.md` · AGENTS.md
Job processors contribute	helix-job-processors `CONTRIBUTING.md` · AGENTS.md
Helix Intake	docs.intake.apps…
Helix Patch	docs.patch.apps…
Helix Patch campaigns	Patch docs — actions & verifiers
IO long-running workflows	orchestrator `LONG_RUNNING_WORKFLOWS.md`
Helix IO adapters	orchestrator `HELIX_ADAPTERS.md`
helix-ee API / SDK	docs.ee…
Job processors	docs.jobs…

Hosted documentation

Product	Docs	OpenAPI
Platform	https://docs.platform.helix-dev.igentify.in	https://openapi.platform.helix-dev.igentify.in
Patch	https://docs.patch.apps.helix-dev.igentify.in	https://openapi.patch.apps.helix-dev.igentify.in
Intake	https://docs.intake.apps.helix-dev.igentify.in	https://openapi.intake.apps.helix-dev.igentify.in
helix-ee	https://docs.ee.helix-dev.igentify.in	https://openapi.ee.helix-dev.igentify.in
Job processors	https://docs.jobs.helix-dev.igentify.in	https://openapi.jobs.helix-dev.igentify.in
IO	https://docs.orchestrator.igentify.in	https://openapi.orchestrator.igentify.in

Helix developer guide — stack, local work, deploy, contribute ​

1. The stack at a glance ​

2. Recommended working model ​

3. Local development by area ​

3.1 Helix Platform (shell) ​

3.2 Helix Apps (Patch, Intake) ​

3.3 helix-ee ​

3.4 Integration Orchestrator — edit workflows (no code) ​

3.5 Integration Orchestrator — adapter / runtime code ​

3.6 helix-job-processors ​

4. Deployment options ​

Deploy commands (dev account) ​

Dev domains (cheat sheet) ​

5. Contribution best practices ​

Isolation (non-negotiable) ​

Git / PR hygiene ​

Contracts and versions ​

Secrets and config ​

Testing before you ask for review ​

Who to involve ​

6. Example team scenarios ​

7. Related docs ​

Hosted documentation ​

Helix developer guide — stack, local work, deploy, contribute

1. The stack at a glance

2. Recommended working model

3. Local development by area

3.1 Helix Platform (shell)

3.2 Helix Apps (Patch, Intake)

3.3 helix-ee

3.4 Integration Orchestrator — edit workflows (no code)

3.5 Integration Orchestrator — adapter / runtime code

3.6 helix-job-processors

4. Deployment options

Deploy commands (dev account)

Dev domains (cheat sheet)

5. Contribution best practices

Isolation (non-negotiable)

Git / PR hygiene

Contracts and versions

Secrets and config

Testing before you ask for review

Who to involve

6. Example team scenarios

7. Related docs

Hosted documentation