Architecture
How a request flows, the subsystems, and the deployment shape.
Under the boundary, every tool call takes a predictable path — and the credential never leaves the server.
How a tool call flows
Your agent calls a meta-tool
Either through the SDK (session.executeTool(...)) or over MCP (STACKLINK_EXECUTE_TOOL).
Stacklink resolves the account
It picks the connected account by accountId/accountAlias (or the session default), loads the
active encrypted credential version, and refreshes it if expired.
The provider executor runs
A provider-specific client calls the real API with credentials that never leave the server. Signed URLs and large payloads are captured as Stacklink artifacts.
Results come back sanitized
The model receives a sanitized response (secrets and signed URLs redacted). Everything is recorded in
tool_execution_logs and linked to the originating platform_request_logs row.
Subsystems at a glance
| Subsystem | Owns |
|---|---|
| Sessions | The per-tenant/user scope: tools, accounts, knowledge, MCP surface. |
| Catalog | Provider toolkits, tools, triggers, branding — reconciled on server start. |
| Connections | Auth configs, connected accounts, encrypted credential versions. |
| Knowledge | Versioned packs, hybrid retrieval, evidence receipts, structured rules. |
| Events | Webhook ingress, polling, the normalize → deliver pipeline. |
| Workbench | Backend control plane over a secure, isolated code/bash sandbox. |
| Billing & usage | Plans, operation classes, metered usage, cost ledger. |
| Observability | platform_request_logs and tool_execution_logs. |
Background workers
Stacklink runs several workers outside the request path: a poller (polling triggers), a webhook-delivery worker (outbound events with retry/dead-letter), connection-health (credential expiry detection), provider-runtime (subscription renewal, job reconciliation), and workbench reconcilers and idle cleanup.
Deployment shape
The backend is a single Fastify service that can also serve the built dashboard from the same origin. The remote workbench runs in a separate isolated sandbox runtime. Knowledge runs from a separate runtime database, built offline and promoted as approved releases.