Architecture / Registry

Node Registry

Canonical registry of all node executor types available in the Nexus orchestration engine. Each node represents a discrete processing unit in a pipeline flow graph.

Version NR-1.0 Date 2026-05-02 Owner Uued Viljapuuaiad Status Active Authority Tier 3

1. Registry Overview

29 node executors across 9 categories, with 20 canvas aliases providing user-friendly naming for the visual pipeline editor.

2. Node Categories

Category Nodes Purpose
Ingest 5 Data entry points: documents, email, SMS, CSV, voice
Intelligence 4 AI/ML processing: NLP, OCR, scoring, matching
Storage 2 Persist and retrieve data from deltaPrism graph
Egress 4 Output channels: email, SMS, HTTP, PDF
Logic 2 Flow control: conditional branching, field transformation
Form 2 Human interaction: data entry forms, approval gates
Validation 1 BDT constraint enforcement on records
Trigger 2 Flow initiation: webhook, schedule
UI 3 Presentation: dashboards, navigation, list views

3. Complete Node Catalogue

3.1 Ingest Nodes

Engine Key Canvas Alias Executor Lines Description
IngestNode DocIngest IngestNodeExecutor 195 Generic document ingestion into deltaPrism. Parses structured/unstructured input.
GmailIngest EmailIngest GmailIngestExecutor 124 Gmail API integration. Extracts subject, body, attachments, metadata.
SmsIngest SMSIngest SmsIngestExecutor 59 SMS message ingestion via Twilio/gateway. Extracts sender, body, timestamp.
BankCsvIngest CSVIngest BankCsvIngestExecutor 152 Bank statement CSV parsing. Column mapping, amount extraction, category detection.
VoiceIngest -- VoiceIngestExecutor 114 Voice call transcription ingestion. Speech-to-text integration.

3.2 Intelligence Nodes

Engine Key Canvas Alias Executor Lines Description
AiTransform AITransform, SentimentNode AiTransformExecutor 119 LLM-powered text transformation. Prompt-directed: summarise, classify, extract, sentiment.
AiTransformVoice -- AiTransformVoiceExecutor 46 Voice-specific AI processing. Tone analysis, intent detection from transcribed audio.
AtlasOcr OCRNode, AtlasOcrNode, AtlasCall AtlasOcrExecutor 112 Document OCR extraction. Structured field extraction from scanned documents, invoices, IDs.
GpuTransform GpuTransformNode GpuTransformNodeExecutor 182 GPU-accelerated batch processing. deltaPrism rule compilation for high-volume evaluation.

3.3 Storage Nodes

Engine Key Canvas Alias Executor Lines Description
StoreNode -- StoreNodeExecutor 120 Write entity records to deltaPrism graph. Enforces BDT validation before persist.
IngestNode DocIngest IngestNodeExecutor 195 Also serves as deltaPrism read/ingest from graph store.

3.4 Egress Nodes

Engine Key Canvas Alias Executor Lines Description
EgressNode -- EgressNodeExecutor 158 Generic output node. Routes results to configured destination.
EmailForward EmailSend EmailForwardExecutor 108 Send email via SMTP/API. Template-driven body, attachments from flow context.
SmsReply SMSSend SmsReplyExecutor 60 Send SMS reply via Twilio/gateway. Template body, recipient from flow context.
HttpForward HTTPPost, GovernmentAPICall HttpForwardExecutor 56 HTTP POST to external API. Configurable headers, auth, retry.
PdfGenerator -- PdfGeneratorExecutor 93 Generate PDF documents from templates. ReportLab-based, data-driven.
ReportGenerator -- ReportGeneratorExecutor 71 Aggregate data into formatted reports. Multi-section, table/chart capable.

3.5 Logic Nodes

Engine Key Canvas Alias Executor Lines Description
ConditionBranch ConditionBranch ConditionBranchExecutor 150 Evaluate Wormwood formula expression. Route flow to true/false branches.
FieldMapper Transformer FieldMapperExecutor 59 Map/rename/transform fields between node outputs and inputs.

3.6 Form Nodes

Engine Key Canvas Alias Executor Lines Description
FormNode -- FormNodeExecutor 110 Render data entry form from entity class schema. Collect user input.
HumanGate ApprovalGate HumanGateNodeExecutor 90 Pause flow execution. Present approval/rejection decision to human operator. Resume on decision.

3.7 Validation Nodes

Engine Key Canvas Alias Executor Lines Description
ValidateNode -- ValidateNodeExecutor 108 Run BDT + lifecycle validation against entity record. Returns pass/fail with error list.

3.8 Trigger Nodes

Engine Key Canvas Alias Executor Lines Description
WebhookTrigger WebhookListen WebhookTriggerExecutor 77 Start flow from incoming HTTP webhook. Parse payload, validate signature.
ScheduleTrigger ScheduleNode SchedulerTriggerExecutor 47 Start flow on cron schedule. Time-based triggering with timezone support.

3.9 UI Nodes

Engine Key Canvas Alias Executor Lines Description
DashboardNode DashboardNode DashboardNodeExecutor 177 Render real-time dashboard. Metrics, charts, status indicators from flow data.
NavMenuNode NavMenuNode NavMenuNodeExecutor 130 Application navigation structure. Menu items, routing, access control per role.
ListViewNode ListViewNode ListViewNodeExecutor 151 Tabular data listing. Sort, filter, paginate entity records. Row actions.
LeadScoreNode LeadScoreNode LeadScoreNodeExecutor 159 Composite scoring for leads/opportunities. Multi-factor weighted calculation.
MatchNode MatchNode MatchNodeExecutor 179 Record matching/deduplication. Fuzzy match on configurable fields, threshold-based.

4. Node Executor Contract

All nodes implement the NodeExecutor abstract base class:

class NodeExecutor(ABC):
    @abstractmethod
    def execute(self, node_config: Dict, input_data: Dict) -> Dict:
        """Execute node logic. Returns output dict for downstream nodes."""

4.1 Contract Guarantees

Aspect Requirement
Input node_config (static configuration from flow JSON) + input_data (upstream node outputs)
Output Dict with at minimum {"status": "success\ error", "data": {...}}
Determinism Same config + same input = same output (except external I/O nodes)
Error handling Raise NodeExecutionError with structured message, never return silently
Side effects Ingest/Egress nodes have external I/O; Logic/Form/Validation are pure

4.2 Node Configuration Schema

Field Type Required Description
type string Yes Node type key (engine key or canvas alias)
id string Yes Unique node instance ID within the flow
name string Yes Human-readable node label
config object Yes Type-specific configuration parameters
position object No Canvas x/y position for visual editor
connections array Yes Downstream node IDs (edges in the flow graph)

5. Canvas Alias Resolution

The orchestration engine resolves canvas aliases to engine executors at flow load time. This allows the visual editor to use friendly names while the engine operates on canonical executor classes.

Canvas Alias Resolves To Rationale
ApprovalGate HumanGate User-facing: "approval" is clearer than "human gate"
OCRNode AtlasOcr Generic name hides vendor (Atlas) dependency
AITransform AiTransform Capitalisation normalisation
SentimentNode AiTransform Specialised prompt config, same executor
SMSSend SmsReply Directional clarity: "send" vs engine's "reply"
HTTPPost HttpForward Protocol-specific name for canvas
EmailSend EmailForward Directional clarity
WebhookListen WebhookTrigger Directional clarity: "listen" = trigger
EmailIngest GmailIngest Generic name hides Gmail-specific implementation
DocIngest IngestNode Document-specific alias
CSVIngest BankCsvIngest Format-specific alias
ScheduleNode ScheduleTrigger Canvas uses "node" suffix convention
GovernmentAPICall HttpForward Domain-specific alias for government integrations

6. Use Case Node Mapping

Use Case Primary Nodes Flow Pattern
Nesto (Worker Compliance) FormNode, ValidateNode, StoreNode, HumanGate, EmailForward Form -> Validate -> Gate -> Store -> Notify
ARC (Lead Pipeline) WebhookTrigger, AiTransform, LeadScoreNode, MatchNode, ConditionBranch, EmailForward Trigger -> Enrich -> Score -> Match -> Branch -> Notify
ENDO (Document Processing) GmailIngest, AtlasOcr, AiTransform, ValidateNode, StoreNode, PdfGenerator Ingest -> OCR -> Extract -> Validate -> Store -> Report
CreativeAnswer (Freelance) WebhookTrigger, AiTransform, LeadScoreNode, ConditionBranch, EmailForward Trigger -> Analyse -> Score -> Route -> Notify
EDR (Entity Registry) IngestNode, ValidateNode, StoreNode, ConditionBranch, ReportGenerator Ingest -> Validate -> Branch -> Store -> Report
AES (Assessment Engine) FormNode, ValidateNode, AiTransform, ConditionBranch, StoreNode, DashboardNode Form -> Validate -> AI -> Branch -> Store -> Dashboard

7. Registry Versioning

Version Date Changes
NR-1.0 2026-05-02 Initial registry: 29 executors, 20 canvas aliases, 9 categories. Extracted from codebase.

Referencing This Registry

The NSD flows section references node registry version via: "node_registry_version": "NR-1.0". The orchestration engine validates that all node types used in flow graphs are declared in the referenced registry version.