Architecture

Faimulus separates unified driver contracts, shared application behavior, and HTTP control-plane concerns. Core owns the reusable runtime and lifecycle; server is its Fastify HTTP/WebSocket adapter.

Faimulus core loads workflow packages, validates their manifests and graphs, and owns durable execution, schedules, callbacks, channels, toolset configuration, and interaction queues. The server exposes that shared runtime through HTTP webhooks, management routes, and WebSocket event streams.

Workspace responsibilities

Workspace	Responsibility	Persistence
@faimulus/driver-sdk	Unified provider, memory, tool, and channel driver contracts and manifest validation	None
@faimulus/core	Workflow engine, built-in and external-runner integration, application services, workspace drivers, SQLite stores, schedules, channels, and runtime leases	runs.sqlite, server-config.sqlite, channels.sqlite, driver data
@faimulus/server	Public HTTP/WebSocket adapter, authentication extraction, webhook parsing, and socket delivery	Core supplied

External drivers and toolsets

Faimulus is an orchestration runtime, not a hardcoded provider stack. It runs workflows, schedules nodes, enforces graph and schema rules, tracks durable run state, and exposes management and execution APIs. It delegates model I/O, memory backends, and channel transports to workspace-supplied drivers, and delegates tool execution connectivity to configured toolsets.

Provider drivers

Provider drivers implement model access behind a shared contract. They are loaded from trusted workspace code and selected by logical model roles from workspace configuration.

The role boundary is deliberate: workflow definitions ask for semantic behavior (for example router, summarization, classification), while config/models.yaml binds those roles to concrete provider-backed models.

• Faimulus responsibility: validate configuration, resolve model-role routing, apply workflow execution policy, and normalize provider failures into runtime envelopes.
• Provider responsibility: authenticate to the model backend, translate request and response payloads, and expose provider-specific capabilities through the common interface.

This keeps workflow logic and node behavior stable even when providers are swapped, versioned, or tuned per environment, and prevents vendor model naming concerns from leaking into workflow business logic.

Memory drivers

Memory drivers provide named persistence surfaces declared in config/memories.yaml. They encapsulate storage details such as file layout, external services, or custom consistency behavior.

• Faimulus responsibility: bind named memory definitions into workflow-visible handles, enforce configuration validation, and coordinate when nodes read or write during execution.
• Memory responsibility: implement read/write/list semantics, durability mechanics, and driver-level safeguards allowed by that memory type.

In practice, Faimulus treats memory as a capability boundary: workflows can use configured memory names, but storage implementation and data layout stay inside the driver.

Channel drivers

Channel drivers handle interactive and out-of-band delivery paths (for example, human approval loops, async progress routing, or external message transport).

• Faimulus responsibility: persist run and checkpoint state, decide when interaction is required, sign callback flows, and resume suspended runs when responses arrive.
• Channel responsibility: connect to the target transport, deliver messages, correlate external responses, and return normalized interaction events.

This allows interaction strategy to vary per deployment while the core suspension and resume lifecycle remains consistent.

Toolsets

Toolsets are named external tool providers configured in config/toolsets.yaml (for example MCP Streamable HTTP endpoints) plus per-tool policy (allow, ask, deny).

• Faimulus responsibility: parse and validate toolset registry data, enforce enablement and policy decisions, interpolate configuration environment references, and present a consistent tool invocation surface to workflows.
• Toolset provider responsibility: host and execute the actual tools, expose supported operations, and return tool results over the provider protocol.

Unlike provider, memory, and channel drivers, toolsets are typically remote integration points defined by configuration rather than compiled workspace driver modules.

Ownership boundary summary

Capability	Faimulus owns	External integration owns
Providers	Role mapping, lifecycle orchestration, error normalization	Backend API auth, model protocol adaptation, provider-specific behavior
Memory	Naming, config validation, runtime coordination	Physical storage, retention model, backend consistency semantics
Channels	Suspend/resume lifecycle, checkpoint durability, callback integrity	Transport delivery, recipient integration, external response bridging
Toolsets	Registry, policy enforcement, invocation gating	Tool hosting, protocol server behavior, tool implementation

Execution flow

1. A host adapter creates the core application, which loads workspace configuration and discovers immediate child directories of WORKSPACE_ROOT/workflows that contain manifest.yaml or flow.yaml.
2. Core bounds file references to the workflow root, parses YAML and inline sources, validates node schemas and graph structure, and performs dependency preflight.
3. A synchronous request executes immediately. An asynchronous request is recorded in SQLite and consumed by the concurrency-limited run service.
4. The built-in scheduler runs ready nodes in parallel unless node semantics require sequential execution. A configured compatible runner may accept ordinary remote-safe runs.
5. Every node returns a success, failure, or suspended envelope. Suspended work stores a checkpoint for later interaction resolution.
6. Terminal async work is polled, streamed, delivered through a signed callback, or routed directly to an in-process channel instance.

Trust boundaries

Workflow files, inline scripts, JavaScript expressions, mounted drivers, MCP servers, model providers, and HTTP targets are trusted deployment inputs. Public endpoints have different authentication behavior; consult the HTTP reference before exposing a service.