Overview

Understanding Xentom's integration architecture is essential for building effective and maintainable integrations. This overview covers the core concepts, design patterns, and architectural decisions that shape how integrations work within the Xentom ecosystem.

Basic Structure

Every integration follows a consistent structure:

src/index.ts

import * as i from '@xentom/integration-framework';
import * as nodes from './nodes';

export default i.integration({
  // Integration nodes
  nodes,

  // Authentication configuration (optional)
  auth: i.auth.token(),

  // Environment variables (optional)
  env: {
    API_VERSION: i.env({
      control: i.controls.text(),
    }),
  },

  // Runs when the integration starts (optional)
  start({ auth, env, state }) {
    state.client = new YourApiClient(auth.token, {
      version: env.API_VERSION,
    });
  },

  // Runs when the integration stops (optional)
  stop({ state }) {
    state.client.cleanup();
  },
});

Core Principles

Xentom integrations are built on several key architectural principles:

Type Safety

Heavy use of TypeScript generics and inference ensures compile-time validation and excellent developer experience with IDE support.

Declarative Configuration

Integrations are defined declaratively, making them easy to understand, test, and maintain.

Component-Based Design

Each integration is composed of reusable components: nodes, pins, controls, and environment variables.

Standard Schema Compliance

Data validation uses the Standard Schema specification, allowing compatibility with popular validation libraries like Valibot, Zod, and ArkType. This provides runtime type safety, clear error messages, and excellent TypeScript integration. See Schema Validation for comprehensive examples and implementation details.

Components

Each integration consists of several key components:

Authentication

Security mechanisms for accessing external services:

Basic Authentication

Basic username and password authentication.

Token Authentication

Grant access through a pre-issued token.

OAuth2 Authentication

Delegate secure authorization to trusted third-party identity providers.

Environment Variables

Global configuration values available throughout the integration.

Nodes

The functional units that appear in the workflow editor:

Trigger Nodes

Start workflows based on external events.

Callable Nodes

Perform actions and can be chained together.

Pure Nodes

Process data without side effects.

Pins

Connection points that define how data flows between nodes:

Execution Pins

Control workflow execution flow.

Data Pins

Carry information and values.

Controls

User interface elements for configuration:

Text Control

Simple text input with template support.

Switch Controls

Boolean toggles.

Select Control

Dropdown menus with static or dynamic options.

Expression Controls

JavaScript code input for advanced users.

This architecture provides a powerful yet approachable foundation for building robust integrations that can handle everything from simple API calls to complex multi-step workflows.