@pxp-nd/flow 1.1.27 → 1.1.30

package/BPM_Propossal.md

@@ -0,0 +1,566 @@
+# BPM + Automation Platform — Design Proposal
+
+**Status:** Draft  
+**Base:** Current Tempo Flows (`twf_*`, `EventHq`, SQS worker) — see [FLOWS.md](./FLOWS.md)  
+**Stack lean (v1):** NestJS + React + PostgreSQL + SQS/BullMQ
+
+---
+
+## 1. Summary — what we want to build
+
+We want a **new process platform** that keeps everything that already works in Tempo Flows (visual automation, action catalog, event + queue, multi-tenant templates) and extends it into a real **BPM** product.
+
+**In short:**
+
+| Today (Flows) | Tomorrow (BPM + Automation) |
+|---------------|-----------------------------|
+| Event → delay → email/push/controller | Same automations, cleaner engine |
+| Mostly linear graphs | Gateways (branch / parallel) with clear UI |
+| Little human workflow | Forms, approvals, assignees, task inbox |
+| No first-class documents | Require / upload / generate documents |
+| Internal controllers mainly | HTTP / webhooks / external connectors |
+| Soft versioning | Immutable process versions |
+| Magic vendor `55` | Explicit **SYSTEM / GROUP / TENANT** catalog scopes |
+
+**Product shape (same engine, two modes):**
+
+1. **Automation** — fire-and-forget graphs (billing alerts, COS push, funnels).  
+2. **BPM** — long-running cases (form → approve → documents → notify → close).
+
+**Builder UX (keep):** left = action palette · center = canvas · right = node form (`schema_json`).
+
+**Migration:** strangler pattern — keep `twf_*` running; migrate process-by-process (e.g. Safe Families first); do not big-bang rewrite.
+
+---
+
+## 2. ER diagram (color legend)
+
+| Color | Meaning |
+|-------|---------|
+| **Amber** | Exists today as `twf_*` → **renamed / evolved** |
+| **Green** | **Completely new** (no direct `twf_*` equivalent) |
+
+```mermaid
+flowchart TB
+  classDef renamed fill:#FFF3CD,stroke:#B8860B,color:#000000,stroke-width:2px
+  classDef newtbl fill:#D1E7DD,stroke:#0F5132,color:#000000,stroke-width:2px
+  classDef legend fill:#F8F9FA,stroke:#6C757D,color:#000000
+
+  subgraph LEGEND["Legend"]
+    L1["AMBER = existing twf_* → renamed/evolved"]
+    L2["GREEN = completely new"]
+    L1:::legend
+    L2:::legend
+  end
+
+  subgraph TENANCY["Tenancy"]
+    TG["bpm_tenant_group"]:::newtbl
+    TGM["bpm_tenant_group_member"]:::newtbl
+    AG["bpm_action_group"]:::newtbl
+  end
+
+  subgraph DESIGN["Design-time"]
+    AT["bpm_action_type<br/>← twf_action_type"]:::renamed
+    A["bpm_action<br/>← twf_action"]:::renamed
+    PD["bpm_process_definition<br/>← twf_flow"]:::renamed
+    PV["bpm_process_version<br/>← split from twf_flow"]:::renamed
+    N["bpm_node<br/>← twf_node"]:::renamed
+    E["bpm_edge<br/>← twf_node_connection"]:::renamed
+    FD["bpm_form_definition"]:::newtbl
+    FV["bpm_form_version"]:::newtbl
+    DT["bpm_document_type"]:::newtbl
+    AP["bpm_approval_policy"]:::newtbl
+  end
+
+  subgraph RUNTIME["Runtime"]
+    PI["bpm_process_instance<br/>← twf_flow_instance"]:::renamed
+    AI["bpm_activity_instance<br/>← twf_node_instance"]:::renamed
+    TK["bpm_token"]:::newtbl
+    T["bpm_task"]:::newtbl
+    TA["bpm_task_action"]:::newtbl
+    DOC["bpm_document"]:::newtbl
+    MSG["bpm_message<br/>← twf_event"]:::renamed
+    JOB["bpm_job"]:::newtbl
+    AUD["bpm_audit_log<br/>← twf_flow_log"]:::renamed
+  end
+
+  TG --> TGM
+  A --> AG
+  TG --> AG
+  AT --> A
+  A --> N
+  PD --> PV
+  PV --> N
+  PV --> E
+  FD --> FV
+  FV -.-> N
+  AP -.-> N
+  DT -.-> N
+  PV --> PI
+  PI --> AI
+  PI --> TK
+  N --> AI
+  AI --> T
+  T --> TA
+  PI --> DOC
+  DT --> DOC
+  MSG --> PI
+  PI --> JOB
+  PI --> AUD
+```
+
+```mermaid
+erDiagram
+    bpm_tenant_group ||--o{ bpm_tenant_group_member : has
+    bpm_tenant_group ||--o{ bpm_action_group : scopes
+    bpm_action_type ||--o{ bpm_action : categorizes
+    bpm_action ||--o{ bpm_action_group : visible_in
+    bpm_action ||--o{ bpm_node : used_by
+    bpm_process_definition ||--o{ bpm_process_version : has
+    bpm_process_version ||--o{ bpm_node : contains
+    bpm_process_version ||--o{ bpm_edge : contains
+    bpm_form_definition ||--o{ bpm_form_version : has
+    bpm_form_version ||--o{ bpm_node : bound_to
+    bpm_approval_policy ||--o{ bpm_node : configures
+    bpm_document_type ||--o{ bpm_node : required_by
+    bpm_process_version ||--o{ bpm_process_instance : instantiates
+    bpm_process_instance ||--o{ bpm_activity_instance : has
+    bpm_process_instance ||--o{ bpm_token : active_at
+    bpm_node ||--o{ bpm_activity_instance : executes_as
+    bpm_activity_instance ||--o{ bpm_task : creates
+    bpm_task ||--o{ bpm_task_action : records
+    bpm_process_instance ||--o{ bpm_document : owns
+    bpm_document_type ||--o{ bpm_document : typed_as
+    bpm_message ||--o{ bpm_process_instance : starts_or_signals
+    bpm_process_instance ||--o{ bpm_job : schedules
+    bpm_process_instance ||--o{ bpm_audit_log : audited_by
+```
+
+**Color checklist**
+
+| Amber — renamed / evolved | Green — new |
+|---------------------------|-------------|
+| `bpm_action_type` ← `twf_action_type` | `bpm_tenant_group` |
+| `bpm_action` ← `twf_action` | `bpm_tenant_group_member` |
+| `bpm_process_definition` ← `twf_flow` | `bpm_action_group` |
+| `bpm_process_version` ← split from `twf_flow` | `bpm_form_definition` / `bpm_form_version` |
+| `bpm_node` ← `twf_node` | `bpm_document_type` |
+| `bpm_edge` ← `twf_node_connection` | `bpm_approval_policy` |
+| `bpm_process_instance` ← `twf_flow_instance` | `bpm_token` |
+| `bpm_activity_instance` ← `twf_node_instance` | `bpm_task` / `bpm_task_action` |
+| `bpm_message` ← `twf_event` | `bpm_document` |
+| `bpm_audit_log` ← `twf_flow_log` | `bpm_job` |
+
+> Tenant identity maps to today’s `vendor_id`. Optional bridge tables `twf_origin_name` / `twf_field_map` can remain for legacy view-based automations; BPM case data lives in `bpm_process_instance.variables`.
+
+---
+
+## 3. Data dictionary
+
+Conventions used below:
+
+- `tenant_id` = vendor id (unless noted).  
+- JSON examples are illustrative.  
+- `visibility_scope`: `SYSTEM` | `GROUP` | `TENANT`.
+
+---
+
+### 3.1 Tenancy
+
+#### `bpm_tenant_group` *(new)*
+
+Groups of tenants that share a catalog slice (e.g. business type).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Group id | `1` |
+| `code` | varchar | Stable code | `SF` |
+| `name` | varchar | Display name | `Safe Families` |
+| `is_active` | bool | Soft enable | `true` |
+
+#### `bpm_tenant_group_member` *(new)*
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Row id | `10` |
+| `tenant_id` | int | Vendor id | `674` |
+| `tenant_group_id` | FK | Group | `1` (`SF`) |
+
+#### `bpm_action_group` *(new)*
+
+Links a GROUP-scoped action to one or more tenant groups.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `action_id` | FK | Action | `111` |
+| `tenant_group_id` | FK | Group that may use it | `1` (`SF`) |
+
+---
+
+### 3.2 Catalog (palette)
+
+#### `bpm_action_type` *(← `twf_action_type`)*
+
+Category in the left palette (Delay, Email, Controller, HTTP, Approval, …).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Type id | `28` |
+| `code` | varchar | Stable type code | `CONTROLLER_EXECUTION` |
+| `name` | varchar | Palette group label | `CONTROLLER EXECUTION` |
+| `schema_json` | json | Shared UI schema for the type | `{ "timeout": { ... } }` |
+| `is_start` | char(1) | Can be a start/trigger type | `N` |
+| `is_delay` | char(1) | Timer-like behavior | `N` |
+| `on_duplicate` | varchar | Hook when process is cloned | `duplicateEmailTemplate` |
+| `is_active` | bool | Visible in palette | `true` |
+
+#### `bpm_action` *(← `twf_action`)*
+
+Reusable step/event definition (stable contract via `code`).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Action id | `111` |
+| `action_type_id` | FK | Category | `28` |
+| `code` | varchar | **Stable API key** (never hardcode numeric id in callers) | `SF SEND COS PUSH` |
+| `name` | varchar | Builder label | `Send Push Notification to COS members` |
+| `description` | text | Help text in palette | `Sends a push when a COS message is posted` |
+| `schema_json` | json | Right-panel form for this action | `{ "subject": {...}, "message": {...} }` |
+| `config_json_template` | json | Defaults / `{{ FIELD }}` placeholders | `{ "subject": "{{ FAMILY_NAME }}" }` |
+| `controller_function` | varchar | Internal handler or connector key | `hq-nd/BusinessTypeSF/sendCircleOfSupportNotification` |
+| `visibility_scope` | varchar | Who can use it | `GROUP` |
+| `owner_tenant_id` | int null | Set when scope = `TENANT` | `null` |
+| `is_enabled` | bool | Kill switch | `true` |
+| `icon` | varchar | Palette icon | `mdi:bell-ring-outline` |
+
+---
+
+### 3.3 Process definition (design-time graph)
+
+#### `bpm_process_definition` *(← `twf_flow` metadata)*
+
+Logical process (many versions).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Definition id | `100` |
+| `key` | varchar | Stable process key | `sf-new-cos-message` |
+| `name` | varchar | Display name | `New COS Message` |
+| `category` | varchar | `automation` or `bpm` | `automation` |
+| `owner_tenant_id` | int null | Owning vendor; null for platform template | `674` |
+| `visibility_scope` | varchar | Who may clone/subscribe | `GROUP` |
+| `icon` | varchar | UI icon | `chatbubbles-outline` |
+| `is_active` | bool | Soft delete | `true` |
+
+#### `bpm_process_version` *(split from `twf_flow`)*
+
+Immutable published graph. Running instances pin a version.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Version id | `45` |
+| `definition_id` | FK | Parent definition | `100` |
+| `version` | int | Monotonic version number | `3` |
+| `status` | varchar | `draft` \| `published` \| `retired` | `published` |
+| `published_at` | timestamp null | Publish time | `2026-07-15T12:00:00Z` |
+| `graph_checksum` | varchar | Optional integrity hash | `sha256:…` |
+
+#### `bpm_node` *(← `twf_node`)*
+
+One element on the canvas.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Node id | `18200` |
+| `version_id` | FK | Process version | `45` |
+| `action_id` | FK null | Catalog action (null for pure gateways/start/end) | `111` |
+| `element_type` | varchar | BPMN-ish type | `serviceTask` / `userTask` / `exclusiveGateway` / `startEvent` |
+| `name` | varchar | Label on canvas | `Send Push Notification to COS members` |
+| `is_init` | bool | Entry / trigger node | `false` |
+| `config_json` | json | Values from right-panel form (`action_config_json` today) | `{ "subject": "{{ REGISTERED_BY_NAME }}", "message": "{{ MESSAGE }}" }` |
+| `form_version_id` | FK null | Bound form (user tasks) | `12` |
+| `approval_policy_id` | FK null | Approval rules | `3` |
+| `document_type_id` | FK null | Required doc type | `null` |
+| `position_x` / `position_y` | int | Canvas coordinates | `120`, `340` |
+
+#### `bpm_edge` *(← `twf_node_connection`)*
+
+Directed connection; may carry a condition (gateway branch).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Edge id | `900` |
+| `version_id` | FK | Process version | `45` |
+| `from_node_id` | FK null | Source; null = link into start | `18199` |
+| `to_node_id` | FK | Target | `18200` |
+| `name` | varchar null | Branch label | `approved` |
+| `condition_expr` | varchar null | Expression for XOR/default | `variables.decision == "approved"` |
+| `is_default` | bool | Default flow on gateway | `false` |
+
+---
+
+### 3.4 Forms, approvals, documents (design-time)
+
+#### `bpm_form_definition` *(new)*
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Form id | `5` |
+| `key` | varchar | Stable key | `sf-need-review` |
+| `name` | varchar | Display name | `Need review form` |
+| `visibility_scope` | varchar | Catalog scope | `GROUP` |
+| `owner_tenant_id` | int null | If `TENANT` | `null` |
+
+#### `bpm_form_version` *(new)*
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Form version id | `12` |
+| `form_id` | FK | Parent form | `5` |
+| `version` | int | Version number | `2` |
+| `schema_json` | json | JSON Schema of fields | `{ "type":"object", "properties": { "notes": { "type":"string" } } }` |
+| `ui_schema` | json | UI layout hints | `{ "notes": { "ui:widget":"textarea" } }` |
+| `status` | varchar | `draft` \| `published` | `published` |
+
+#### `bpm_approval_policy` *(new)*
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Policy id | `3` |
+| `code` | varchar | Stable code | `SF_AREA_ANY` |
+| `policy_type` | varchar | `ANY` \| `ALL` \| `N_OF_M` | `ANY` |
+| `quorum_n` | int null | Required when `N_OF_M` | `null` |
+| `assignee_resolver` | json | How to resolve approvers | `{ "type":"expression", "resolver":"sfAreaApprovers", "args": { "familyAreaId": "{{ variables.familyAreaId }}" } }` |
+| `outcomes` | json | Allowed outcomes | `["approved","rejected","changes_requested"]` |
+
+#### `bpm_document_type` *(new)*
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Doc type id | `7` |
+| `code` | varchar | Stable code | `HOST_AGREEMENT` |
+| `name` | varchar | Label | `Host agreement PDF` |
+| `mime_allowlist` | json | Allowed MIME types | `["application/pdf"]` |
+| `max_size_mb` | int | Upload limit | `10` |
+| `visibility_scope` | varchar | Catalog scope | `GROUP` |
+
+---
+
+### 3.5 Runtime
+
+#### `bpm_process_instance` *(← `twf_flow_instance`)*
+
+One running (or completed) case.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Instance id | `5001` |
+| `version_id` | FK | Pinned process version | `45` |
+| `tenant_id` | int | Owning vendor | `674` |
+| `business_key` | varchar | External correlation id | `cos-message:8891` |
+| `status` | varchar | `running` \| `waiting` \| `completed` \| `failed` \| `cancelled` | `running` |
+| `variables` | json | Case data (replaces heavy reliance on SQL views) | `{ "referralId": 321, "familyName": "The Smith Family", "familyInitials": "SM", "message": "Can someone cover Friday?" }` |
+| `started_at` / `ended_at` | timestamp | Lifecycle | `2026-07-16T14:01:00Z` / `null` |
+
+#### `bpm_activity_instance` *(← `twf_node_instance`)*
+
+One execution of a node inside an instance.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Activity id | `80001` |
+| `instance_id` | FK | Process instance | `5001` |
+| `node_id` | FK | Definition node | `18200` |
+| `status` | varchar | `pending` \| `active` \| `completed` \| `failed` \| `skipped` | `completed` |
+| `input_json` | json | Snapshot of inputs | `{ "subject": "Jane Doe", "message": "…" }` |
+| `output_json` | json | Snapshot of outputs | `{ "sent": 3, "skipped": 1 }` |
+| `error_message` | text null | Failure detail | `null` |
+| `started_at` / `completed_at` | timestamp | Timing | … |
+
+#### `bpm_token` *(new)*
+
+Active position(s) in the graph (required for parallel gateways).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Token id | `60` |
+| `instance_id` | FK | Process instance | `5001` |
+| `node_id` | FK | Current node | `18200` |
+| `status` | varchar | `active` \| `consumed` | `active` |
+| `parent_token_id` | FK null | For parallel forks | `null` |
+
+#### `bpm_task` *(new)*
+
+Human inbox item (form / approval).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Task id | `900` |
+| `activity_id` | FK | Related activity | `80010` |
+| `instance_id` | FK | Process instance (denormalized for queries) | `5001` |
+| `tenant_id` | int | Tenant | `674` |
+| `task_type` | varchar | `FORM` \| `APPROVAL` | `APPROVAL` |
+| `title` | varchar | Inbox title | `Approve posted need #441` |
+| `assignee` | varchar null | Claimed user id/email | `approver@sf.org` |
+| `candidate_users` | json | Potential assignees | `["a@sf.org","b@sf.org"]` |
+| `candidate_groups` | json | Role/group keys | `["SF_AREA_12"]` |
+| `due_at` | timestamp null | SLA due | `2026-07-17T18:00:00Z` |
+| `status` | varchar | `open` \| `completed` \| `cancelled` | `open` |
+| `form_version_id` | FK null | Form to render | `12` |
+| `payload_json` | json | Task-specific data | `{ "needId": 441, "kind": "post" }` |
+
+#### `bpm_task_action` *(new)*
+
+Audit of human actions on a task.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Action id | `1200` |
+| `task_id` | FK | Task | `900` |
+| `actor` | varchar | Who acted | `a@sf.org` |
+| `action` | varchar | `approve` \| `reject` \| `comment` \| `reassign` \| `complete` | `approve` |
+| `comment` | text null | Optional note | `Looks good` |
+| `data_json` | json null | Submitted form fields | `{ "notes": "OK" }` |
+| `created_at` | timestamp | When | `2026-07-16T15:00:00Z` |
+
+#### `bpm_document` *(new)*
+
+Uploaded or generated file for an instance.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Document id | `70` |
+| `instance_id` | FK | Process instance | `5001` |
+| `document_type_id` | FK | Type | `7` |
+| `tenant_id` | int | Tenant | `674` |
+| `file_name` | varchar | Original name | `host-agreement.pdf` |
+| `s3_key` | varchar | Storage key | `bpm/674/5001/host-agreement.pdf` |
+| `mime_type` | varchar | MIME | `application/pdf` |
+| `status` | varchar | `required` \| `uploaded` \| `approved` \| `rejected` | `uploaded` |
+| `uploaded_by` | varchar null | Actor | `coach@sf.org` |
+
+#### `bpm_message` *(← `twf_event`)*
+
+Inbound event / signal that starts or resumes a process.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Message id | `56953` |
+| `action_code` | varchar | Trigger action code (or process key) | `SF NEW COS MESSAGE` |
+| `tenant_id` | int null | Known tenant if resolved | `674` |
+| `business_key` | varchar null | Correlation | `cos-message:8891` |
+| `payload_json` | json | Event body / origin row snapshot | `{ "id": 8891, "referralId": 321, "familyName": "The Smith Family", "familyInitials": "SM" }` |
+| `desc_job_name` | varchar | Caller context (like today) | `CircleOfSupport/createMessage` |
+| `status` | varchar | `pending` \| `processed` \| `failed` | `processed` |
+| `process_instance_id` | FK null | Instance created/signaled | `5001` |
+
+#### `bpm_job` *(new)*
+
+Async work: timers, HTTP retries, delayed continuations (worker queue rows).
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Job id | `300` |
+| `instance_id` | FK null | Related instance | `5001` |
+| `activity_id` | FK null | Related activity | `80001` |
+| `job_type` | varchar | `TIMER` \| `HTTP` \| `EMAIL` \| `PUSH` \| `CONTINUE` | `PUSH` |
+| `run_at` | timestamp | When eligible | `2026-07-16T14:01:05Z` |
+| `attempts` | int | Retry count | `1` |
+| `max_attempts` | int | Cap | `4` |
+| `payload_json` | json | Worker payload | `{ "actionCode": "SF SEND COS PUSH", "config": { ... } }` |
+| `status` | varchar | `scheduled` \| `running` \| `done` \| `failed` | `done` |
+| `last_error` | text null | Last failure | `null` |
+
+#### `bpm_audit_log` *(← `twf_flow_log`)*
+
+Immutable trail for support and compliance.
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `id` | PK | Log id | `10001` |
+| `instance_id` | FK null | Process instance | `5001` |
+| `tenant_id` | int null | Tenant | `674` |
+| `event_type` | varchar | `INSTANCE_STARTED` \| `TASK_COMPLETED` \| `NODE_FAILED` \| … | `NODE_FAILED` |
+| `message` | text | Human-readable summary | `Push connector timeout` |
+| `details_json` | json | Structured detail / stack excerpt | `{ "activityId": 80001, "error": "ETIMEDOUT" }` |
+| `created_at` | timestamp | When | `2026-07-16T14:02:00Z` |
+
+---
+
+## 4. Multi-tenancy (catalog visibility) — short
+
+| Scope | Who sees the action/form/template |
+|-------|-----------------------------------|
+| `SYSTEM` | All tenants |
+| `GROUP` | Tenants in linked `bpm_tenant_group` (via `bpm_action_group`) |
+| `TENANT` | Only `owner_tenant_id` |
+
+Builder palette = `SYSTEM ∪ GROUP(member) ∪ TENANT(owner)`.  
+**Always re-validate on publish and execute** (never trust UI alone).  
+Instance/task/document data is always hard-scoped by `tenant_id`.
+
+Replace today’s “vendor 55 runs for everyone” with **platform/group templates + tenant clone or subscription**.
+
+---
+
+## Appendix A — Keep / improve from current Flows
+
+**Keep:** stable action `code`, action catalog + `schema_json`, node graph, event + SQS worker, template duplicate, instance history, 3-pane builder.
+
+**Improve:** human tasks, approvals, forms, documents, gateway UX, case variables, HTTP connectors, immutable versions, observability.
+
+Details of the current engine: [FLOWS.md](./FLOWS.md).
+
+---
+
+## Appendix B — Target capabilities (MVP → later)
+
+| Capability | Approach |
+|------------|----------|
+| Forms | `bpm_form_*` + User Task node |
+| Approvals | `bpm_approval_policy` + `bpm_task` |
+| Branching | `exclusiveGateway` / `parallelGateway` + `bpm_edge.condition_expr` + `bpm_token` |
+| Documents | `bpm_document_type` + `bpm_document` + S3 |
+| External APIs | Action types `HTTP_REQUEST`, `WEBHOOK_WAIT`, connectors |
+| Automations | Same engine; category=`automation`; service tasks only |
+
+---
+
+## Appendix C — Stack & migration
+
+| Layer | Choice |
+|-------|--------|
+| API + engine v1 | **NestJS** modular monolith |
+| Workers | NestJS + SQS/BullMQ |
+| UI | React (evolve Harmony builder + task inbox) |
+| DB | PostgreSQL preferred |
+| Later | Optional Go workers if metrics demand |
+
+**Migration:** keep `twf_*` live → adapter from `EventHq.add` → migrate SF processes first → retire legacy write path when ready.
+
+---
+
+## Appendix D — Open decisions
+
+1. Expression language: JSONLogic vs CEL vs JMESPath  
+2. Form tech: RJSF vs Formily vs custom  
+3. Postgres vs MySQL for the new DB  
+4. Inbox inside Harmony vs separate app  
+5. BPMN XML export in v1 or JSON-only  
+6. Tenant groups: reuse `business_type` vs dedicated packs  
+7. Global automations: subscription (recommended) vs fan-out listener  
+
+---
+
+## Appendix E — Example process (Safe Families)
+
+```text
+Start (SF NEW COS MESSAGE / SF NEW POSTED NEED)
+  → Service Task: notify (push)
+  → [BPM] User/Approval Task (optional)
+  → Exclusive Gateway (approved / rejected)
+  → Service Task: decision notification
+  → End
+```
+
+Same trigger model as today; richer graph when human steps are needed.

package/README.md

@@ -1 +1,437 @@
-# flow-nd
+# Tempo Flows (Workflow Engine)
+
+This document describes how automation **flows** work in Tempo: database structure, runtime pipeline, and how to trigger or assemble them.
+
+Flows are a **node-graph automation engine**. Definitions and runtime state live in MySQL tables prefixed `twf_*`. Core entities and graph execution come from **`@pxp-nd/flow`**. Tempo adds business orchestration via `EventHq`, `FlowHQ`, and an SQS worker.
+
+---
+
+## High-level architecture
+
+```text
+Business code (controllers / PHP jobs)
+        │
+        ▼
+EventHq.add({ actionId, descJobName, dataId })
+        │
+        ├─► twf_event (status: pending)
+        └─► SQS FIFO (FLOW_QUEUE_URL)
+                │
+                ▼
+        worker.ts  →  EventHq.processSingleEvent({ eventId })
+                │
+                ├─► Find active twf_node rows for actionId
+                ├─► Query origin view (origin_name + origin_key = dataId)
+                ├─► Vendor match + event_config conditions
+                ├─► Create twf_flow_instance
+                └─► NodeInstanceController.RecursiveInstance() walks the DAG
+```
+
+### Key Tempo files
+
+| File | Role |
+|------|------|
+| `src/modules/hq-nd/controllers/EventHq.ts` | Enqueue events to SQS; process a single event into flow instances |
+| `src/modules/hq-nd/controllers/Flow.ts` (`FlowHQ`) | Duplicate templates, chained flows, funnel lists/statistics |
+| `src/worker.ts` | SQS consumer (started when `INIT_FLOW_WORKER=Y`) |
+| `src/config.ts` / `ormconfig.js` | Registers `flow-nd` module and merges flow entities |
+
+Entities such as `Flow`, `Node`, `Action`, `Event`, `FlowInstance`, `NodeInstance` are **not** redefined in Tempo; they come from `@pxp-nd/flow`.
+
+---
+
+## How execution works (summary)
+
+1. **Fire an event**  
+   Application code looks up `twf_action` by stable `code`, then calls `EventHq.add` with:
+   - `actionId` — PK of the action  
+   - `dataId` — PK value in the action’s origin view (`origin_key`)  
+   - `descJobName` — caller context for debugging  
+
+2. **Enqueue**  
+   `EventHq.add` inserts a `twf_event` (`status = pending`) and sends a message to SQS containing `eventId`.
+
+3. **Worker**  
+   `pollQueue()` in `src/worker.ts` receives the message, deletes it from the queue, then calls `processSingleEvent` with retries (1s / 5s / 10s / 20s). Failures after retries go to Slack (`SLACK_TEMPO_ERROR`).
+
+4. **Match flows**  
+   For every active `twf_node` with that `action_id`:
+   - Load one row: `SELECT * FROM {origin_name} WHERE {origin_key} = {dataId}`
+   - Load parent `twf_flow` — must be `is_active = 1` and **`status = 'on'`**
+   - Vendor filter: `flow.vendor_id === view.vendor_id` **OR** `flow.vendor_id === 55` (global Qorus flows)
+   - Optional `event_config` filters on the action/node
+
+5. **Run the graph**  
+   Create `twf_flow_instance`, then walk `twf_node` / `twf_node_connection` via `RecursiveInstance()`. Each step creates `twf_node_instance` rows. Errors are stored in `twf_flow_log`.
+
+---
+
+## Database ER diagram
+
+```mermaid
+erDiagram
+    twf_action_type ||--o{ twf_action : "categorizes"
+    twf_action ||--o{ twf_node : "used by"
+    twf_action ||--o{ twf_event : "triggered as"
+    twf_action ||--o{ twf_flow_instance : "started by"
+    twf_flow ||--o{ twf_node : "contains"
+    twf_flow ||--o{ twf_flow_instance : "instantiates"
+    twf_node ||--o{ twf_node_connection : "master"
+    twf_node ||--o{ twf_node_connection : "child"
+    twf_node ||--o{ twf_node_instance : "executes as"
+    twf_flow_instance ||--o{ twf_node_instance : "has steps"
+    twf_origin_name ||--o{ twf_field_map : "maps fields"
+
+    twf_action_type {
+        int action_type_id PK
+        varchar name
+        varchar schema_json
+        varchar is_start
+        varchar is_delay
+        varchar controller
+        varchar on_duplicate
+        tinyint is_active
+    }
+
+    twf_action {
+        int action_id PK
+        int action_type_id FK
+        varchar code "stable contract"
+        varchar name
+        varchar origin_name "DB view"
+        varchar origin_key "PK column in view"
+        varchar controller_function
+        varchar schema_json
+        varchar event_config
+        varchar config_json_template
+        tinyint is_active
+    }
+
+    twf_flow {
+        int flow_id PK
+        int vendor_id "0/55 template or vendor"
+        varchar code
+        varchar name
+        varchar type "template|custom"
+        varchar template_type "funnel|flow|null"
+        varchar status "must be on to run"
+        varchar enabled
+        tinyint is_active
+        varchar publish
+        varchar flow_type
+    }
+
+    twf_node {
+        int node_id PK
+        int flow_id FK
+        int action_id FK
+        varchar is_init "Y = entry/trigger"
+        varchar is_end
+        varchar action_config_json "runtime values"
+        varchar approval_config
+        tinyint is_active
+    }
+
+    twf_node_connection {
+        int node_connection_id PK
+        int node_id_master "NULL = init edge"
+        int node_id_child FK
+        varchar condition
+        tinyint is_active
+    }
+
+    twf_event {
+        int event_id PK
+        int action_id FK
+        int data_id "origin PK value"
+        varchar desc_job_name
+        varchar status "pending|processed"
+        tinyint is_active
+    }
+
+    twf_flow_instance {
+        int flow_instance_id PK
+        int flow_id FK
+        int data_id
+        int action_id
+        varchar origin_name
+        varchar origin_key
+        varchar status
+        varchar flag_name
+        int flag_value
+        tinyint is_active
+    }
+
+    twf_node_instance {
+        int node_instance_id PK
+        int node_id FK
+        int flow_instance_id FK
+        timestamp run_time
+        timestamp schedule
+        varchar status
+        json extra_args
+        tinyint is_active
+    }
+
+    twf_origin_name {
+        int origin_name_id PK
+        varchar name "view name"
+        varchar originKey
+        tinyint is_active
+    }
+
+    twf_field_map {
+        int field_map_id PK
+        int origin_name_id FK
+        varchar name
+        varchar alias
+        varchar type
+        tinyint is_active
+    }
+
+    twf_flow_log {
+        int flow_log_id PK
+        varchar error_custom_message
+        varchar error_message
+        text stack_trace
+        tinyint is_active
+    }
+```
+
+> Note: Some FK relationships are logical (enforced in application / TypeORM) rather than hard MySQL foreign keys on every column.
+
+---
+
+## Runtime pipeline diagram
+
+```mermaid
+flowchart LR
+    A[Business code] -->|Action.findOne by code| B[EventHq.add]
+    B --> C[(twf_event pending)]
+    B --> D[SQS FLOW_QUEUE_URL]
+    D --> E[worker.ts pollQueue]
+    E --> F[EventHq.processSingleEvent]
+    F --> G{Active nodes for actionId}
+    G --> H[Query origin view by dataId]
+    H --> I{flow status=on<br/>vendor match or vendor 55}
+    I -->|yes| J[(twf_flow_instance)]
+    J --> K[RecursiveInstance DAG walk]
+    K --> L[(twf_node_instance)]
+    I -->|no| M[Skip node]
+    F -.->|errors| N[(twf_flow_log)]
+```
+
+---
+
+## Table reference
+
+| Table | Role |
+|-------|------|
+| `twf_action_type` | Category of step (EVENT, EMAIL, DELAY, PAGE, CHAINED FLOW, CONTROLLER EXECUTION, …) |
+| `twf_action` | Reusable action / event definition; stable API via `code` |
+| `twf_flow` | Flow definition (template or vendor custom instance) |
+| `twf_node` | One step in a flow; points at one action; holds `action_config_json` |
+| `twf_node_connection` | Directed edges (DAG). Init connection uses `node_id_master = NULL` |
+| `twf_event` | Async event queue row |
+| `twf_flow_instance` | One execution of a flow for a given `dataId` |
+| `twf_node_instance` | Per-step execution record |
+| `twf_origin_name` | Registry of DB views used as event data sources |
+| `twf_field_map` | Column aliases for Harmony builder / templating |
+| `twf_flow_log` | Execution / processing errors |
+
+### Important `twf_flow` fields
+
+| Field | Meaning |
+|-------|---------|
+| `type` | `template` (blueprint) or `custom` (vendor instance) |
+| `template_type` | `funnel`, `flow`, or null |
+| `status` | Must be **`on`** for `EventHq` to execute the flow |
+| `vendor_id` | `0` / `55` for global templates; vendor id for instances. **Vendor 55** matches any vendor’s events |
+| `code` | Optional stable identifier (e.g. `NEW_EMAIL_LIST`) |
+
+### Important `twf_action` fields
+
+| Field | Meaning |
+|-------|---------|
+| `code` | Unique string — always resolve with `Action.findOne({ code })` |
+| `origin_name` / `origin_key` | View + PK used when resolving `dataId` |
+| `schema_json` | UI form for Harmony flow builder |
+| `event_config` | Optional filters: `{ "filters": [{ "originField", "nodeField" }] }` |
+| `controller_function` | Tempo controller path for CONTROLLER EXECUTION (e.g. `hq-nd/BusinessTypeSF/sendApprovalNotification`) |
+
+### Common `action_type_id` values (active)
+
+| ID | Name | Notes |
+|----|------|--------|
+| 9 | EVENT | Trigger / listener node |
+| 10 | EMAIL NOTIFICATION | Send email |
+| 11 | DELAY | Wait step |
+| 16 | PAGE | Opt-in / bridge pages |
+| 24 | CHAINED FLOW | Invoke another flow |
+| 26 | PUSH NOTIFICATION | Mobile push |
+| 28 | CONTROLLER EXECUTION | Call a Tempo controller method |
+
+`on_duplicate` on the action type drives post-processing when duplicating a flow (`duplicateEmailTemplate`, `duplicatePageTemplate`, `duplicateChainedFlow`).
+
+---
+
+## JSON configuration layers
+
+1. **`twf_action_type.schema_json`** — shared UI schema for the type  
+2. **`twf_action.schema_json`** — per-action UI overrides  
+3. **`twf_node.action_config_json`** — **actual values at runtime** for that node  
+
+Examples of `action_config_json`:
+
+| Type | Typical keys |
+|------|----------------|
+| PAGE | `templateBuilderId`, `emailListId`, `smsListId`, `title` |
+| EMAIL | `to`, `subject`, `templateId` |
+| DELAY | `quantity`, `type` (`hours` / `minutes` / `days`) |
+| CHAINED / EMAIL_JOURNEY | `flowId` |
+| CONTROLLER / push (SF) | `subject`, `message`, `mobileActionId`, `notificationType` |
+
+Templates may use `{{ FIELD }}` placeholders resolved from the origin view row (`config_json_template` / node config).
+
+---
+
+## Triggering a flow from TypeScript
+
+```typescript
+import { Action, Event } from '@pxp-nd/flow';
+import EventHq from './EventHq';
+
+const action = await Action.findOne({ code: 'ADD EMAIL LIST ADDRESS' });
+if (action) {
+  const eventInstance = new EventHq('hq-nd/EventHq', Event);
+  await eventInstance.add({
+    actionId: action.actionId,
+    descJobName: 'formLegato',           // caller context
+    dataId: resInsert.emailListAddrId,   // PK in action.origin_name
+  }, manager);
+}
+```
+
+Rules:
+
+- Prefer **`EventHq.add()`** in Tempo (enqueues SQS). Do not bypass the queue for production event firing.
+- Never hardcode `action_id`; always look up by `code`.
+- `dataId` must exist in the action’s origin view.
+- Flow must be `status = 'on'` and `is_active = 1`.
+
+Events may also be fired from legacy PHP (e.g. billing jobs calling `hq-nd/EventHq/add`).
+
+---
+
+## Assembling / creating flows
+
+### A. Duplicate a template (preferred for vendor instances)
+
+```typescript
+const flowHq = new FlowHQ('hq-nd/FlowHQ');
+const result = await flowHq.duplicateFlow(
+  { flowId: templateFlowId, vendorId, name: 'Bridge Funnel' },
+  manager
+);
+// Activate if needed:
+await manager.createQueryBuilder().update('twf_flow')
+  .set({ status: 'on' })
+  .where('flowId = :flowId', { flowId })
+  .execute();
+```
+
+Template IDs often come from env:
+
+- `TEMPLATE_BRIDGE_FUNNEL_FLOW_ID` (default `149`)
+- `TEMPLATE_QORD_BRIDGE_FUNNEL_FLOW_ID` (default `3419`)
+
+### B. Patch init node after duplicate
+
+```typescript
+await manager.createQueryBuilder().update('twf_node')
+  .set({ actionConfigJson: JSON.stringify({ emailListId }) })
+  .where('flowId = :flowId AND isInit = :isInit', { flowId, isInit: 'Y' })
+  .execute();
+```
+
+### C. Chained funnel → email journey
+
+Use `FlowHQ.addChainedFlow()` (duplicates child flow, copies `emailListId`, activates).
+
+### D. SQL registration
+
+Typical order:
+
+1. Optional `twf_action_type`
+2. `twf_action` (EVENT + step actions) with `WHERE NOT EXISTS (... code ...)`
+3. If new origin: `twf_origin_name` + `twf_field_map`
+4. Optional full graph: `twf_flow` → init `twf_node` → connections → step nodes
+5. Register in `src/modules/hq-nd/database/jaime-scripts.ts` as `JRR-HQ-[STORY]-[SEQ]`
+
+Modern SF-style DML often registers **actions only** and lets the Harmony UI assemble the graph.
+
+---
+
+## Vendor matching (important)
+
+When processing an event, Tempo runs a flow if:
+
+```text
+flow.vendorId === viewVendorId  OR  flow.vendorId === 55
+```
+
+So:
+
+- A **vendor-specific** flow only runs for that vendor’s data.
+- A **vendor 55 (Qorus)** flow runs for **any** vendor that fires the matching event (global notifications).
+
+---
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `FLOW_QUEUE_URL` | SQS FIFO queue for async events |
+| `INIT_FLOW_WORKER` | `Y` starts `pollQueue()` from `server.ts` |
+| `TEMPLATE_BRIDGE_FUNNEL_FLOW_ID` | Default bridge funnel template |
+| `TEMPLATE_QORD_BRIDGE_FUNNEL_FLOW_ID` | Qord bridge funnel template |
+| `SLACK_TEMPO_ERROR` | Channel for worker failures after retries |
+
+---
+
+## Naming conventions
+
+- Action `code`: UPPER CASE with spaces — e.g. `NEW POSTED NEED`, `BILLING NOT PROCESSED`, `SF SEND COS PUSH`
+- Funnel templates: `type = 'template'`, `template_type = 'funnel'`
+- Email / automation templates: `type = 'template'`, `template_type = 'flow'` (or null)
+- Vendor copies after `duplicateFlow`: `type = 'custom'`
+
+---
+
+## Do / Don’t
+
+**Do**
+
+- Find actions by `code`
+- Duplicate templates for vendor flows; keep them `status = 'on'` when they should run
+- Register new origins in `twf_origin_name` (+ field maps) before using them in actions
+- Use `EventHq.add` so processing goes through SQS
+
+**Don’t**
+
+- Hardcode `action_id`
+- Auto-sync `twf_*` schema (`synchronize` stays false)
+- Skip SQS for production event firing
+- Hand-build full vendor graphs in TypeScript when a template + `duplicateFlow` exists
+
+---
+
+## Controllers that commonly fire events
+
+Examples in Tempo: `Site`, `Vendor`, `Member`, `Package`, `MemberAccounts`, `EmailList`, `PageTemplate`, `Extra`, `CloudFrontFlow`, mobile `Subscriptions`, `helpers/Site.ts`. Legacy Harmony PHP jobs may also call `EventHq/add` (e.g. billing).
+
+---
+
+## Related Cursor rules
+
+Project conventions for flows are also summarized in `.cursorrules` under **Flows (Workflow Engine)**. Keep this document and those rules aligned when changing the event pipeline or `twf_*` contracts.

package/dist/controllers/Flow.js

@@ -719,7 +719,7 @@ let Flow = class Flow extends core_1.Controller {
                 //valid controllerValidation
                 const { action: { actionType } } = node;
                 const { validationController } = actionType;
-                const nodeController = new Node_2.default('flow-nd');
+                const nodeController = new Node_2.default('flow-nd', Node_1.default);
                 await nodeController.executeValidationController({ validationController, actionConfigJson: values, showException: true });
                 //end valid controller
                 const missingRequired = [];

package/dist/controllers/FlowInstance.d.ts

@@ -13,6 +13,7 @@
  * Last modified  :
  *   ISSUE        DATE        NAME                DESCRIPTION
  *  9141239986   16-May-2025  Mercedes Zambrana   Save flagName and FlagValue
+ *  EF-23        08-Oct-2026  Favio Figueroa      GET_LOCK instead of flag, skipped=200, axios timeout
  */
 import { EntityManager } from 'typeorm';
 import { Controller } from '@pxp-nd/core';

package/dist/controllers/FlowInstance.js

@@ -14,6 +14,7 @@
  * Last modified  :
  *   ISSUE        DATE        NAME                DESCRIPTION
  *  9141239986   16-May-2025  Mercedes Zambrana   Save flagName and FlagValue
+ *  EF-23        08-Oct-2026  Favio Figueroa      GET_LOCK instead of flag, skipped=200, axios timeout
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -39,16 +40,11 @@ const Event_1 = __importDefault(require("../entity/Event"));
 const Flow_1 = __importDefault(require("../entity/Flow"));
 const Action_1 = __importDefault(require("../entity/Action"));
 const FlowLog_1 = __importDefault(require("../entity/FlowLog"));
+const dbLock_1 = require("../helpers/dbLock");
 class FlowInstance extends core_1.Controller {
     async processPending(params, manager) {
-        const flag = await common_1.GlobalData.findOne({ data: 'wf_processing_pending_flows_flag' });
-        if (flag) {
-            if (flag.value == 'true') {
-                throw new core_1.PxpError(400, 'Already processing pending flows');
-            }
-            flag.value = 'true';
-            let flowInstanceIdProcessing = -1;
-            await (0, typeorm_1.getManager)().save(flag);
+        let flowInstanceIdProcessing = -1;
+        const { acquired } = await (0, dbLock_1.withDbLock)('wf_process_pending', async () => {
             try {
                 await this.eventProcesss(manager);
                 const maxFlows = await common_1.GlobalData.findOne({ data: 'wf_max_concurrent_flows_process' });
@@ -69,17 +65,17 @@ class FlowInstance extends core_1.Controller {
                 }
             }
             catch (error) {
-                flag.value = 'false';
-                await (0, typeorm_1.getManager)().save(flag);
+                // The lock is released by withDbLock's finally block
                 const log = new FlowLog_1.default();
                 log.errorCustomMessage = `Error executing ${flowInstanceIdProcessing} in FlowInstance-> processPending `;
                 log.errorMessage = error.message;
                 log.stackTrace = error.stack || '';
-                (0, typeorm_1.getManager)().save(log);
+                await (0, typeorm_1.getManager)().save(log).catch(e => console.error('[flow] FlowLog save failed', e.message));
                 throw new core_1.PxpError(400, 'Error processing flow: ' + flowInstanceIdProcessing);
             }
-            flag.value = 'false';
-            await (0, typeorm_1.getManager)().save(flag);
+        });
+        if (!acquired) {
+            return { success: true, skipped: true, reason: 'already running' };
         }
         return { success: true };
     }
@@ -115,7 +111,7 @@ class FlowInstance extends core_1.Controller {
                 log.errorCustomMessage = `Error processing event ${newEvent.eventId} in FlowInstance-> eventProcesss `;
                 log.errorMessage = error.message;
                 log.stackTrace = error.stack || '';
-                (0, typeorm_1.getManager)().save(log);
+                await (0, typeorm_1.getManager)().save(log).catch(e => console.error('[flow] FlowLog save failed', e.message));
             }
         }
     }

package/dist/controllers/NodeInstance.d.ts

@@ -13,6 +13,7 @@
  * Last modified  :
  *  ISSUE         DATE           AUTHOR              DESCRIPTION
  *  25-Apr-2025   8914754251     Mercedes Zambrana   Validate and use node?.action?.controllerFunction
+ *  08-Oct-2026   EF-23          Favio Figueroa      GET_LOCK instead of flag, skipped=200, axios timeout
  */
 import { EntityManager } from "typeorm";
 import { Controller } from "@pxp-nd/core";

package/dist/controllers/NodeInstance.js

@@ -14,6 +14,7 @@
  * Last modified  :
  *  ISSUE         DATE           AUTHOR              DESCRIPTION
  *  25-Apr-2025   8914754251     Mercedes Zambrana   Validate and use node?.action?.controllerFunction
+ *  08-Oct-2026   EF-23          Favio Figueroa      GET_LOCK instead of flag, skipped=200, axios timeout
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -40,6 +41,7 @@ const ActionType_1 = __importDefault(require("../entity/ActionType"));
 const Action_1 = __importDefault(require("../entity/Action"));
 const lodash_1 = __importDefault(require("lodash"));
 const FlowInstance_1 = __importDefault(require("../entity/FlowInstance"));
+const dbLock_1 = require("../helpers/dbLock");
 //TODO replace this flow-nd need tobe independent library
 const common_1 = require("@pxp-nd/common");
 let NodeInstance = class NodeInstance extends core_1.Controller {
@@ -101,6 +103,7 @@ let NodeInstance = class NodeInstance extends core_1.Controller {
                                 "Content-Type": "application/json",
                             },
                             data: mergeJson,
+                            timeout: Number(process.env.FLOW_ACTION_TIMEOUT_MS || 30000),
                         };
                         const resControllerAxios = await (0, core_1.__)((0, axios_1.default)(config));
                         if ('data' in resControllerAxios && resControllerAxios.data) {
@@ -120,6 +123,7 @@ let NodeInstance = class NodeInstance extends core_1.Controller {
                                 "Content-Type": "application/json",
                             },
                             data: mergeJson,
+                            timeout: Number(process.env.FLOW_ACTION_TIMEOUT_MS || 30000),
                         };
                         const resControllerAxios = await (0, core_1.__)((0, axios_1.default)(config));
                         if ('data' in resControllerAxios && resControllerAxios.data) {
@@ -152,21 +156,13 @@ let NodeInstance = class NodeInstance extends core_1.Controller {
             log.errorCustomMessage = `Error executing ${flowInstance.flowInstanceId} in NodeInstance-> RecursiveInstance `;
             log.errorMessage = error.message;
             log.stackTrace = error.stack || '';
-            (0, typeorm_1.getManager)().save(log);
+            await (0, typeorm_1.getManager)().save(log).catch(e => console.error('[flow] FlowLog save failed', e.message));
         }
         return {};
     }
     async ProcessDelay(params, manager) {
-        const flag = await common_1.GlobalData.findOne({
-            data: "wf_processing_delay_nodes_flag",
-        });
-        if (flag) {
-            if (flag.value == "true") {
-                throw new core_1.PxpError(400, "Already processing pending flows");
-            }
-            flag.value = "true";
-            await (0, typeorm_1.getManager)().save(flag);
-            let nodeInstanceIdProcessing = -1;
+        let nodeInstanceIdProcessing = -1;
+        const { acquired } = await (0, dbLock_1.withDbLock)("wf_process_delay", async () => {
             try {
                 const maxNodes = await common_1.GlobalData.findOne({
                     data: "wf_max_concurrent_delay_process",
@@ -216,12 +212,12 @@ let NodeInstance = class NodeInstance extends core_1.Controller {
                 }
             }
             catch (error) {
-                flag.value = "false";
-                await (0, typeorm_1.getManager)().save(flag);
+                // The lock is released by withDbLock's finally block
                 throw new core_1.PxpError(400, "Error processing node: " + nodeInstanceIdProcessing);
             }
-            flag.value = "false";
-            await (0, typeorm_1.getManager)().save(flag);
+        });
+        if (!acquired) {
+            return { success: true, skipped: true, reason: "already running" };
         }
         return { success: true };
     }

package/dist/helpers/dbLock.d.ts

@@ -0,0 +1,4 @@
+export declare function withDbLock<T>(name: string, fn: () => Promise<T>): Promise<{
+    acquired: boolean;
+    result?: T;
+}>;

package/dist/helpers/dbLock.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDbLock = void 0;
+/**
+ * Named MySQL lock helper (GET_LOCK / RELEASE_LOCK).
+ *
+ * GET_LOCK is bound to the MySQL session, so the lock is taken and released on the
+ * same dedicated QueryRunner. Never use a transaction manager or getManager() here:
+ * those may run on a different pooled connection.
+ *
+ *  ISSUE         DATE           AUTHOR              DESCRIPTION
+ *  EF-23         08-Oct-2026    Favio Figueroa      GET_LOCK instead of flag, skipped=200, axios timeout
+ */
+const typeorm_1 = require("typeorm");
+async function withDbLock(name, fn) {
+    var _a, _b, _c, _d;
+    const qr = (0, typeorm_1.getConnection)(process.env.DB_WRITE_CONNECTION_NAME).createQueryRunner();
+    await qr.connect();
+    let got = 0;
+    try {
+        // GET_LOCK names are server-wide; prefix with the schema so environments sharing a MySQL instance do not block each other
+        const rows = await qr.query("SELECT GET_LOCK(CONCAT(DATABASE(), ':', ?), 0) AS got", [name]);
+        got = Number((_b = (_a = rows === null || rows === void 0 ? void 0 : rows[0]) === null || _a === void 0 ? void 0 : _a.got) !== null && _b !== void 0 ? _b : 0);
+        if (got !== 1)
+            return { acquired: false };
+        const result = await fn();
+        return { acquired: true, result };
+    }
+    finally {
+        if (got === 1) {
+            const rel = await qr
+                .query("SELECT RELEASE_LOCK(CONCAT(DATABASE(), ':', ?)) AS rel", [name])
+                .catch(() => [{ rel: 0 }]);
+            if (Number((_d = (_c = rel === null || rel === void 0 ? void 0 : rel[0]) === null || _c === void 0 ? void 0 : _c.rel) !== null && _d !== void 0 ? _d : 0) !== 1) {
+                // Lock could not be released on this session: drop the physical connection
+                // so MySQL frees the lock instead of returning it to the pool still held.
+                const c = qr.databaseConnection;
+                if (c === null || c === void 0 ? void 0 : c.destroy)
+                    c.destroy();
+            }
+        }
+        await qr.release().catch(() => { });
+    }
+}
+exports.withDbLock = withDbLock;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pxp-nd/flow",
-  "version": "1.1.27",
+  "version": "1.1.30",
   "description": "Workflow module for pxp-nd framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",