Skip to content
Demiton

Adapter Architecture

Adapters provide the integration boundary between the Demiton platform and external systems. All communication with external systems occurs through adapters — never through direct HTTP calls inside workflow logic or API handlers.

Adapter responsibilities

Authentication — adapters manage authentication with external systems. This includes OAuth 2.0 tokens, API keys, service account credentials, and connection strings.

Protocol handling — adapters communicate using system-specific protocols: REST APIs, OData, SQL connections, SFTP, SMTP. Protocol complexity is isolated from the workflow runtime.

Response normalization — external systems return data in different shapes. Adapters normalize these responses into a standard SovereignEnvelope before the data enters the workflow pipeline.

The Sovereign Envelope

Every adapter response returns a SovereignEnvelope:

{
  "records": [...],
  "metrics": { "execution_time_ms": 120, "count": 42, "byte_size": 8192 },
  "trace": { "protocol": "odata", "strategy": "...", "timestamp": "..." },
  "narrative": { "technical_message": "...", "clerk_remark": "...", "bureaucratic_status": "..." },
  "metadata": {},
  "schema_v": "DFS-031-A"
}

This ensures consistent behavior across all workflows regardless of the originating system.

Adapter factory

Adapters are resolved and instantiated through the adapter factory:

get_adapter(connection_type, credentials, system_type, environment)

Resolution priority:

  1. System type — exact match on the connector’s system type
  2. Inferred system type — inferred from connector metadata
  3. Connection type — generic protocol fallback (SFTP, SQL, SMTP)
  4. Deterministic failure — if all resolution fails, an error is thrown

Never instantiate adapters directly. Silent fallback is prohibited — adapters must fail explicitly.

Adapter design rules

Adapters must:

  • remain stateless between calls
  • return a SovereignEnvelope
  • support simulation mode (dry_run=True) for all write operations

Adapters must not:

  • execute workflow logic
  • mutate platform database state
  • store sensitive data to disk
  • make calls to external systems outside of their designated operation

Resource discovery

Adapters expose available datasets through a discovery process. When a connector is saved, discovery runs automatically and returns resource descriptors including:

  • dataset name
  • supported capabilities (FETCH, PUSH, LOOKUP)
  • accepted parameters
  • field schema

These resources are stored in the platform resource registry and become available as workflow step targets.

Adding a new connector

  1. Create an adapter class in app/adapters/{category}/{name}/adapter.py inheriting from BaseAdapter
  2. Implement discover_resources() and optionally get_field_manifest()
  3. Add metadata.py with the adapter’s structured metadata
  4. Register the adapter in app/adapter_runtime/registry.py under SYSTEM_ADAPTER_REGISTRY
  5. Run scripts/gen_connector_docs.py to generate the docs stub

See the connectors section for per-adapter documentation.