System overview
Connectors sits between a caller and an external service. It turns a reviewed operation and a permitted Connection into an execution, while keeping provider credentials in its own custody. It also admits and stores provider events for consumers.
This handbook describes the 0.6.4 implementation. Its diagrams group responsibilities for readers; the ESS specification currently declares a smaller set of components and does not generate this system map.
The boundaries
Pan the full-size diagram: swipe or scroll, or focus the canvas and use the arrow keys.
The arrows distinguish requests, provider events, and configuration data; the unarrowed line marks storage ownership. Identity authenticates hosted callers. Connectors owns receiver-side admission and provider execution. Products own the conversation and approval experience.
Within the runtime, transports adapt shared application contracts, admission forms the required proofs, and adapters execute provider behavior. Event intake has its own admission and persistence path. The invocation flow and event sequence show those paths separately. These responsibilities need not run as separate processes.
Follow one Slack mention
A person has added a hosted companion bot. Someone mentions it in a Slack channel, and the person's application proposes a reply in that thread. This is an architecture example, with an already configured deployment; the Slack guide covers setup.
We call the companion Connection C1, the admitted mention E1, the operation description D1, and an issued approval A1. These are explanatory labels, not request values.
- Establish C1. The person's Connect Session places credentials in Connector custody. It does not issue permission for arbitrary writes.
- Receive E1. The Socket Mode supervisor normalizes and persists the mention before acknowledging Slack. Only an admitted consumer receives it.
- Describe the proposed reply.
Discovery returns D1 for
slack-chat-post-message; the reply selects C1 and its exact input. - Approve the action. Verified human authority issues A1 for that operation, Connection, subject, and input. E1 itself is not hosted approval.
- Attempt the reply. Hosted admission checks the Grant and current description, redeems A1 once, and dispatches. A missing outcome remains uncertain; it does not justify blindly retrying a write.
The example depends on the hosted runtime prerequisites. The specification comparison shows which parts of this path are also declared in ESS.
Subsystem ownership
- Catalog owns provider declarations, selection, traits, provenance, and deterministic artifacts. Start in catalog-build and connector-spec.
- Clients and transports own argument parsing and wire adaptation. The CLI, client, and server expose shared contracts.
- Application and authority own use cases, admission, Grants, approvals, and inert execution plans. See service and domain.
- Credentials and state own bounded storage operations and custody. Runtime bindings implement the SecretStore and StateStore ports.
- Adapters and drivers own provider semantics and admitted effects. The factory selects them; dispatch passes requests across the effect boundary.
- Runtime composition owns configuration, listeners, storage bindings, and supervisors. See composition.
Integration adapters implement the reusable backend port. Runtime composition selects their
concrete implementations; the thin CLI does not own a second implementation of provider behavior.
The maintenance catalog command compiles declarations. The user-facing connectors command
runs and accesses deployments.
The nouns across the boundaries
| Noun | Meaning |
|---|---|
| Provider | Reviewed capabilities and credential requirements of an external provider. |
| Integration | A provider enabled and configured by a deployment. |
| Connection | An authorized instance through which an external account or target can be used. |
| Grant | Connector-owned permission to use a Connection for bounded operations or events. |
| Invocation | One execution attempt of one operation through one Connection. |
| Channel | A configured path by which provider events enter Connectors. |
| Event | A normalized provider fact, with attribution and provenance. |
More columns: swipe horizontally, or focus the table and use the arrow keys.
A catalog entry alone grants no access. Authentication does not permit use of every Connection. Credential custody alone does not make a provider callable: a custody-only provider can hold a credential while exposing no request surface.
What stays outside Connectors
Identity owns hosted login, principals, and general identity authority. Products own their user experience and catalog browsing. External providers own their APIs and upstream account policy. Connectors owns receiver-side admission and the permissions, credentials, execution, and event state needed to reach those providers.
The deployment chapter shows how these responsibilities are assembled. The specification chapter explains which parts also have an executable model.
Overview · Next: Connections and authority