Skip to content

canonical(connectors): two connector families model one concept (knowledge/connectors vs integrations) — owner decision needed #13632

Description

@mrveiss

Part of #13623. Decision issue — needs an owner call before either family grows further. No implementation proposed here.

Two connector families model the same concept

autobot-backend/knowledge/connectors/ autobot-backend/integrations/
base class AbstractConnector (base.py:63) BaseIntegration (base.py:73)
shape ingestion: discover_sources / fetch_content / detect_changes / sync action: get_available_actions / execute_action
registry ConnectorRegistry (registry.py:66) CapabilityRegistry (capability_registry.py:64)
credentials ConnectorCredentialStore (ADR-007, encrypted, owner-scoped) own request path, base.py:125-149
egress per-connector aiohttp per-request aiohttp.ClientSession
sync machinery checkpointing, change detection, retry/backoff, migrate_config none

Slack, Notion, and GitHub exist in both families: knowledge/connectors/{slack,notion}.py and gitlab.py, versus integrations/{slack,notion,github}_integration.py.

So the same provider is configured twice, credentialed through two different mechanisms, and reached over two unguarded HTTP paths — which is also why child #13625 has to fix egress in two places instead of one.

Why now

The external implementation reviewed for #13623 demonstrates that one provider definition can serve discovery, credentials, and execution together: a single definition carries auth config, action contracts, and scopes, with a registry that lazily loads the executor only when an action runs. That is an existence proof that the split is not inherent to the problem.

This is explicitly not an "adopt external code" item. It is our canonical-source question, and it is cheaper to answer before more providers land in either family.

Options for the owner

  1. Converge on one definition + one registry + one credential store, with ingestion and action as two capabilities of a single provider. Highest cost, removes the duplication permanently.
  2. Keep both families but unify the seams — one credential store, one guarded egress path, one capability-flag scheme (feat(connectors): no declared-vs-executable capability flags — unwired features are only found by retrospective audits #13631) — while leaving the two base classes alone. Much cheaper; the duplicate provider definitions remain.
  3. Formally separate the concerns — declare ingestion and action genuinely different domains, document the boundary in ARCHITECTURE_EXCEPTIONS.md, and stop treating the overlap as debt.

Recommendation if a decision is needed quickly: option 2, because it removes the security-relevant duplication (credentials, egress) without a large refactor, and does not foreclose option 1 later.

Acceptance criteria

  • Owner picks an option
  • Decision recorded in docs/developer/ARCHITECTURE_EXCEPTIONS.md or an ADR
  • If option 1 or 2: follow-up issues filed for the chosen seams
  • If option 3: the boundary is documented and this issue closes

Activity

  1. mrveiss commented on Sep 12, 2026

    @mrveiss
    OwnerAuthor

    Owner decision, 2026-09-12: one provider definition, reached in phases. Each provider (Slack, Notion, GitHub/GitLab, and the rest) is defined once, and that one definition serves discovery, ingestion and actions. Credentials come from one store, ConnectorCredentialStore (ADR-007), and outbound calls use one guarded egress path. knowledge/connectors and integrations migrate behind it; neither family grows independently in the meantime. This unblocks #16428.

  2. added this to the Backlog milestone on Sep 12, 2026
  3. added
    needs-decisionBlocked on an owner decision; options and a recommendation are on the issue
    on Sep 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions