NodeFox logoNodeFox

Architecture

NodeFox architecture is designed for teams that need both adaptive AI behavior and operational control. The core principle is simple: represent workflow behavior explicitly, then execute it deterministically with inspectable contracts.

Quick navigation

Architectural model

NodeFox uses a directed graph as the workflow source of truth. In practice, each workflow can be treated as a JSON graph contract containing:

  • node definitions and configuration
  • data routes
  • activation routes
  • slot/flag constraints
  • schema and tool attachments

This framing makes design reviews, incident analysis, and change governance substantially easier than relying on UI layout alone.

Foundation architecture goals

The architecture is optimized for two concurrent outcomes:

  • Adaptive behavior: AI reasoning, tools, code, branching, and iterative flows
  • Deterministic operations: predictable transitions, bounded execution, and repeatable control behavior

Runtime planes

NodeFox can be reasoned about as five cooperating planes.

1. Authoring plane

Where systems are modeled:

  • Network View graph authoring
  • Schema and contract design
  • Node settings and slot flags
  • Reusable custom-node and subflow assets

2. Execution plane

Where graph state transitions run:

  • deterministic runtime control behavior
  • eligibility checks by slot/flag rules
  • controlled parallel execution for independent nodes
  • deterministic branch transition evidence

3. Integration plane

Where external systems are connected:

  • Reader/Writer/API boundaries
  • Functions and MCP tool attachments
  • file/network/cloud I/O controls
  • credential and permission boundaries

4. Interface plane

Where humans interact with workflows:

  • Apps forms and validation
  • operator review and approval surfaces
  • human-in-the-loop decisions

5. Governance plane

Where safety, policy, and audit controls live:

  • schema validation
  • decision gates and acceptance-aware routing
  • tool scope controls
  • run-level evidence retention

Deterministic runtime behavior

NodeFox applies deterministic orchestration behavior through explicit graph contracts and runtime rules. Teams can reason about eligibility, branch ownership, release boundaries, and fallback behavior without relying on hidden callback chains.

This preserves operational clarity as workflows become branch-heavy and cross-functional.

Rust and WASM runtime layer

NodeFox runtime architecture is designed around a Rust + WASM execution core for predictable performance and memory safety characteristics.

Why this matters architecturally:

  • deterministic graph-step behavior without VM warmup variability
  • efficient JSON parsing/validation at run time
  • consistent client/runtime behavior across local execution contexts
  • stronger safety posture for state-heavy orchestration workloads

At the workflow layer, this appears as stable execution stages, typed contracts, and predictable branch transitions under load.

Activation edge architecture

NodeFox separates data transport from execution authorization:

  • Data edge: payload transfer between slots
  • Activation edge: execution signal without payload transfer

Why this matters:

  • safer approval-release models
  • cleaner quality-gate loop transitions
  • reduced accidental execution of high-impact nodes

Slot and typing architecture

NodeFox combines explicit slot channels with typed boundaries:

  • slot-based routing contracts
  • JSON Schema output guarantees
  • selector and $N reference expansion
  • nested path access for structured payloads

This supports dynamic composition while preventing hidden contract drift.

Typed architecture principles:

  • schema-first boundaries at points where downstream writes depend on structure
  • slot-level contracts for explicit payload movement
  • JSON as the portable interchange layer for workflows, runs, and exports
  • typed function and MCP tool contracts for safer model/tool interaction

Flow-control architecture patterns

Branching and OnPass

Decision nodes support explicit route selection through deterministic rules and OnPass mappings.

Looping with max safeguards

Loops should be bounded by explicit max-iteration controls and fallback branches.

Quality-gate architecture

Design quality loops with deterministic pass/fail/escalate outcomes and explicit operator override paths.

Fan-out and fan-in

  • fan-out distributes one output across multiple branches
  • fan-in converges multiple branches into a controlled merge point

Use Optional-slot constraints at convergence points to avoid partial merges.

Parallel processing

Independent branches can execute in the same step batch, increasing throughput while preserving deterministic step semantics.

Composability architecture

Network node composition

Subflow composition enables modular architecture where shared logic is packaged once and reused with explicit contracts.

Marketplace and reusable assets

Marketplace-oriented packaging allows teams to distribute vetted nodes and patterns while maintaining governance standards.

Local-first, privacy, and security orientation

Architecture-level privacy/security posture comes from explicit boundaries:

  • local-first workflow handling patterns
  • constrained external write points
  • scoped tool access
  • inspectable route-level control
  • policy-aware approval gates

Security improves when behavior is explicit at design time and observable at run time.

Model swapping architecture

NodeFox is designed so model/provider changes do not require full orchestration redesign.

Practical pattern:

  1. keep branch and policy logic in graph structure (Decision/Code), not provider-specific prompt hacks
  2. enforce typed output contracts with schemas
  3. isolate provider-specific prompt/model settings within Conversation configuration
  4. validate quality/cost behavior by route after swap before broad rollout

This lets teams switch model families while preserving operational control architecture.

Operational architecture: analytics and governance

NodeFox architecture supports operational decision-making through:

  • run-level evidence by node/branch
  • cost-aware workflow analysis patterns
  • incident-oriented trace inspection
  • governance controls aligned to risk class

Collaboration and change governance

Treat workflow artifacts as versioned engineering assets:

  1. export graph artifacts from workspaces
  2. store them in source control
  3. review diffs with code/policy changes
  4. tie deployment approval to reviewed graph changes

This pattern strengthens cross-team collaboration and audit readiness.

Export and sharing formats

Teams commonly share workflows as JSON artifacts or bundle/zip packages, depending on scope:

  • JSON-first exports for diff-friendly review in source control
  • zip/bundle exports for multi-asset handoff and environment migration
  • link sharing for smaller, fast-review artifacts

For production governance, teams usually pair export workflows with Git-based review and approval routines.

Architecture guidance for beta adoption

  1. Start with one critical workflow family.
  2. Enforce schema and routing contracts early.
  3. Put high-impact writes behind activation-gated approvals.
  4. Bound loops and fallback behavior before rollout.
  5. Use run/cost analytics for post-launch tuning.
  6. Promote stable modules into reusable composable assets.

Related docs