Chainbox

Architecture

Chainbox is an "execution-first" backend framework for Next.js that eliminates traditional API endpoints.

Instead of defining REST/GraphQL routes, developers define "Logical Functions" in src/app/_chain/. These functions are directly callable from the client or other functions via a Call() method, with the framework handling the transport, security, and execution.

Core Architecture

Logical Functions & Registry

core/Registry.ts

  • Location: Functions are located in src/app/_chain.
  • Dynamic Loading: The Registry dynamically loads these functions using jiti for robust runtime TypeScript support. It also supports JavaScript and WebAssembly (WASM).
  • Addressing: Functions are addressed by dot-notation name (e.g., User.Create) or content hash.

Execution Engine

core/Executor.ts

This is the heart of the system. The execution follows a strict pipeline:

onStart
RateLimit
→
Policy
RBAC Check
→
Execute
Handler
→
onEnd
Audit/Telemetry

Context (ctx)

Every function receives a context object providing access to:

  • ctx.call: Invoke other functions.
  • ctx.db: Database access (Supabase or Firebase).
  • ctx.kv / ctx.blob: Storage adapters.
  • ctx.parallel: Parallel execution helper.

Mesh & Transport

transport/Mesh.ts, core/ExecutionPlanner.ts

API Node
Local Execution
Compute Node
Heavy.*
  • Location Transparency
    • Location Transparency

      The ExecutionPlanner decides whether a function runs strictly Locally (same process) or on a Remote Node.

    • Planner Logic

      It uses CHAINBOX_MESH_NODES and CHAINBOX_MESH_ROUTES environment variables to route calls based on regex patterns (e.g., Heavy.* -> compute-node).

    • Circuit Breaker

      The Mesh transport includes a robust circuit breaker (Closed -> Open -> Half-Open) to handle network failures and prevent cascading crashes.

    • Batching

      Supports _ParallelExecute which batches multiple remote calls to the same node into a single HTTP request (/execute/batch).

    Security Model

    Zero-Surface

    No public API endpoints exist for specific features. Only a generic /execute endpoint exists on Mesh Nodes.

    Identity Propagation

    The system expects a JWT. If present, it creates a scoped database client for every request, forwarding the Identity to enforce security (e.g., Supabase RLS) at the database layer. (core/DbAdapter.ts)

    Inter-Node Security

    Calls between mesh nodes are signed and verified to prevent unauthorized command injection. (core/RequestSigner.ts)

    Permissions

    The Executor checks generic role-based permissions defined in the function source before running.

    Client SDK

    client/Client.ts

    See the Client SDK Guide for implementation details.

    Isomorphic Design:

    • Server-Side (Next.js SSR/API): Uses Local transport to execute functions directly in-process for max speed.
    • Client-Side (Browser): Uses Http transport to POST to the backend.

    Key Dependencies:

    • @supabase/supabase-js: Default database and auth provider.
    • firebase-admin: Optional provider for Firebase/Firestore support.
    • undici: High-performance HTTP client for the Mesh transport.
    • jiti: Runtime TypeScript compilation for loading user functions.
    • jose: JWT handling.