Connector Architecture¶

Overview¶

Floh's connector system provides a unified interface for integrating with external services, whether SaaS platforms, on-premise applications, or custom APIs. Connectors abstract the specifics of each integration behind a standardized execution model, allowing workflows to interact with any system through a consistent set of commands.

Design Principles¶

Multi-modal execution — Support built-in, scripted, OAS-derived, and external connectors through a single registry
Secure by default — Sandboxed script execution, encrypted secrets, and scoped permissions
Observable — Integrated logging with configurable levels, impact analysis, and audit trails
Testable — Built-in mock mode at multiple granularity levels
Evolvable — Schema versioning with breaking change detection

Execution Models¶

┌─────────────────────────────────────────────────────────────────┐
│                    Connector Registry                           │
│                                                                 │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌───────────┐│
│  │  Built-in   │  │   Script   │  │    OAS     │  │  External ││
│  │  (Native)   │  │ (QuickJS)  │  │ (Generated)│  │  (HTTP)   ││
│  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘  └─────┬─────┘│
│         │               │               │               │       │
│         ▼               ▼               ▼               ▼       │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌───────────┐│
│  │ TypeScript  │  │ Worker     │  │ Worker     │  │  HTTP     ││
│  │ function    │  │ Thread +   │  │ Thread +   │  │  POST     ││
│  │ call        │  │ QuickJS VM │  │ QuickJS VM │  │  /execute ││
│  └────────────┘  └────────────┘  └────────────┘  └───────────┘│
└─────────────────────────────────────────────────────────────────┘

Built-in (`built_in`)¶

Native TypeScript connectors compiled into the server. These have direct access to Node.js APIs and are registered in the connector registry at startup. Examples include the http and delay connectors.

Best for: Core integrations that ship with Floh, performance-critical connectors.

Script (`script`)¶

Custom JavaScript connectors executed in a sandboxed QuickJS environment via Node.js worker_threads. Scripts communicate with the host through a controlled floh.* API surface.

Best for: Custom integrations, user-authored connectors, connectors that need isolation.

OAS-Derived (`oas`)¶

Connectors auto-generated from OpenAPI 3.x specifications. The OAS parser extracts operations, parameters, and security schemes to produce commands and a generated script that runs in the same QuickJS sandbox as script connectors.

Best for: Rapid integration with APIs that provide OpenAPI specs.

External (`external`)¶

Remote connectors accessed over HTTP. Floh sends a POST request to the connector's /execute endpoint with the command, parameters, and metadata. External connectors implement a standardized protocol.

Best for: Connectors running in separate processes, microservices, or managed by third parties.

Data Flow¶

Workflow Step → StepExecutor → Mock Check → ConnectorRegistry
                    │                              │
                    ▼                              ▼
              ConnectorLogger            Execution Model Router
                    │                    ┌────┬────┬────┬────┐
                    ▼                    │BI  │Scr │OAS │Ext │
              LogService                 └────┴────┴────┴────┘
                    │                              │
                    ▼                              ▼
              system_log table            ConnectorResult

The StepExecutor receives a connector step from the workflow engine
It looks up the connector definition from the database
A ConnectorLogger is created with the connector's configured log level
If mock mode is active (step, connector, run, or system level), mock execution runs instead
Otherwise, the ConnectorRegistry routes execution based on execution_model
The result is returned to the workflow engine as output variables

Database Schema¶

`connector_definition` table¶

Column	Type	Description
`id`	UUID	Primary key
`name`	VARCHAR	Unique connector name
`type`	VARCHAR	Connector type (maps to registry handler)
`description`	TEXT	Human-readable description
`version`	VARCHAR	Semantic version
`execution_model`	VARCHAR	`built_in`, `script`, `oas`, `external`
`script_source`	TEXT	JavaScript source for script/OAS connectors
`mock_data`	JSONB	Static mock scenarios per command
`mock_script`	TEXT	JavaScript source for dynamic mocks
`mock_enabled`	BOOLEAN	Whether mock mode is active
`log_level`	VARCHAR	Minimum log level: trace/debug/info/warn/error/fatal
`debug_logging`	BOOLEAN	Override log level to debug when true
`oas_spec`	TEXT	Original OpenAPI spec (for reference)
`endpoint_url`	VARCHAR	External connector endpoint URL
`endpoint_auth`	JSONB	Authentication config for external endpoints
`schema_version`	VARCHAR	Schema version for breaking change tracking
`category`	VARCHAR	Organizational category (e.g., crm, hr, finance)
`tags`	JSONB	Array of tags for filtering
`icon`	VARCHAR	Icon identifier for UI display
`deprecated_at`	TIMESTAMP	When the connector was deprecated

`system_log` table additions¶

Column	Type	Description
`connector_id`	VARCHAR	Links log entries to a specific connector

Security Model¶

Secret Encryption¶

Connection configuration containing secrets (API keys, tokens, passwords) is encrypted at rest using AES-256-GCM. Secret fields are identified via the configSchema — any field with secret: true is encrypted before storage and decrypted only at execution time.

Script Sandboxing¶

Script connectors run inside quickjs-emscripten VMs in isolated worker_threads:

Memory limit: Configurable per connector (default 16 MB)
CPU limit: Execution timeout (default 30s, configurable)
No filesystem access: Scripts cannot read/write files
No network access: All HTTP calls go through floh.http.* proxied to the main thread
No module imports: Scripts must be self-contained

Permission Model¶

Permission	Operations
`connector:read`	List, view, get registry, impact analysis
`connector:manage`	Create, update, delete, test, execute, parse OAS

Module Structure¶

packages/server/src/modules/connectors/
├── registry.ts            # Connector registry and execution dispatch
├── repository.ts          # Database operations
├── routes.ts              # API endpoints
├── connector-logger.ts    # Structured logging via LogService
├── connector-debug.ts     # Console debug logging (CONNECTOR_DEBUG env)
├── mock-engine.ts         # Mock execution engine
├── schema-versioning.ts   # Breaking change detection
├── impact-analysis.ts     # Workflow impact scanner
├── oas-parser.ts          # OpenAPI spec parser
├── script-runtime.ts      # Worker thread management
├── script-worker.ts       # QuickJS sandbox (runs in worker)
├── agent-protocol.ts      # On-premise agent protocol
├── agent-routes.ts        # WebSocket agent endpoints
├── rotate-keys.ts         # Secret key rotation
├── authifi-connector.ts   # Built-in Authifi connector
├── authifi-client.ts      # Authifi API client
└── test-connectors.ts     # Built-in test connectors