Sources vs providers

The distinction between sources and providers is the design decision that keeps Echo's API stable as the system grows. Understanding it explains why adding a database or a new Git host never adds a new endpoint.

Sources are kinds of knowledge

A source is a category of knowledge: code, graph, docs, company docs, work items, commits & PRs, or database. Each source has a defined schema — the shape of the entities it contains and the relations it participates in. The source is what the API consumer thinks in.

Providers are where knowledge comes from

A provider is the external system a source pulls data from. The code source might be fed by GitHub, GitLab, or Azure DevOps. The work items source might be fed by Jira, Azure Boards, or Linear. The provider handles authentication, pagination, and the wire format of the upstream system.

Why this matters

When Echo adds support for a new provider — say, Bitbucket for code — the code source gains a new feed, but the API surface stays identical. The consumer still calls search with sources: ["code"] and gets the same hit shape. No new endpoint, no new MCP tool, no client-side change.

Source            Example providers
─────────────────────────────────────────
code              github, azure_devops, gitlab
graph             (derived from code — no external provider)
docs              (generated from graph — no external provider)
company_docs      confluence, notion, sharepoint
work_items        jira, azure_boards, linear
commits           github, azure_devops, gitlab
pull_requests     github, azure_devops, gitlab
database          postgresql, mysql, sqlserver

The graph and docs sources are special: they have no external provider. Graph is derived deterministically from the code source. Docs are generated from the graph. They participate in the same faceted contract as every other source.

One source, many providers

A project can have multiple providers for the same source. Two GitHub repos and one Azure DevOps repo all feed the code source. Search hits from all three are fused into one ranked list — the consumer never needs to know which provider produced a given hit.

Next: Refs.