Integration Provider Boundaries

Summary

Provider boundaries explain how external APIs, files, messages, maps, tokens, and delivery systems enter the platform without becoming domain architecture. This is the shared stop for ServiceTitan, QuickBooks Online, Spectrum, Microsoft Graph, Postmark, Radar, web portals, OCR, LLMs, and data-sync linkage.

Reader Question

Where should provider-specific behavior stop, and what internal contract should domain workflows consume instead?

Surface Or Workflow

Operators see provider behavior as sync status, delivery result, document preview, geocoded candidate, portal download, or command diagnostic. Engineers enter through integrations/, capability services, sync diagnostics, and provider-specific tests.

Lifecycle

The external boundary produces a response, file, token, webhook, error, or side effect. Integration code translates it into typed internal values or records. Capability services decide how the rest of the platform should use those values. Domain workflows then record operational state, issues, artifacts, or commands.

Outbound side effects follow the same rule: a workflow may request a send, sync, move, or update, but provider calls stay behind integration or capability services and expose retryable, diagnostic results.

Child Threads

Implementation Boundaries

Provider adapters live under integrations; shared sync linkage under services/data_sync; geocoding under services/geocoding; notifications under services/notifications; auth under services/auth; OCR and LLM capability services under services/ocr and services/llm; integration tests under tests/integrations.

Tradeoffs

Provider boundaries add trace hops. The payoff is that domain workflows can reason in internal terms and support can tell whether a failure belongs to the provider, adapter, capability service, domain state machine, or operator repair surface.

Visual

The current visual is a graph neighborhood. The intended visual is a provider boundary map from external system to adapter, typed contract, capability service, domain workflow, diagnostic, and repair path.

Boundary Pattern

The provider-boundary pattern starts with a simple rule: provider vocabulary should not become platform vocabulary by accident. External systems have their own identifiers, status codes, retry behavior, object models, rate limits, field names, and error shapes. The platform may need all of that information, but domain workflows should not be forced to reason directly in provider terms. Integration code should translate the provider edge into internal contracts that services can consume.

That translation is not merely cosmetic. A provider may return a success code for a partial result, require polling for completion, use mutable external identifiers, or treat duplicate writes differently than the platform does. Provider adapters preserve the messy details. Capability services decide what those details mean for the platform. Domain services then decide what state transition, issue, artifact, or repair action should follow.

The pattern applies in both directions. Inbound provider data becomes typed internal evidence. Outbound provider actions become commands or delivery requests with idempotency, diagnostics, and results. A workflow may decide that an invoice should be synced, a message should be sent, a document should be downloaded, or an address should be geocoded. The actual provider call should remain behind the boundary.

Examples Across The Platform

ServiceTitan-like operational sources are broad and messy. They can supply customers, jobs, technicians, payroll facts, invoices, memberships, materials, and operational context. The platform should not let every domain write its own source interpretation. Instead, ingestion, lakehouse services, data-sync packages, and domain services should normalize those facts into internal models.

Accounting providers are different. They are often outbound targets or reconciliation partners. The important boundary is not just parsing a response; it is preserving source-to-target linkage, preventing duplicate writes, recording provider outcomes, and allowing repair when a command cannot safely continue. A failed accounting sync should become diagnostic state, not a lost exception.

Collaboration providers such as Microsoft Graph and SharePoint sit between documents, mailboxes, folders, identities, and workflow artifacts. Their APIs are powerful, but workflows should consume document access, mailbox access, or collaboration capability rather than raw provider clients. That keeps preconstruction, POA, notifications, and other domains from embedding provider protocol assumptions.

Delivery providers such as Postmark turn communication intent into external messages. The boundary must preserve channel policy, stream choice, recipient context, payload identity, provider response, and failure diagnostics. A domain should ask to deliver a reviewed payload; notification services and provider adapters should own delivery semantics.

Geocoding and LLM providers follow the same shape. The platform needs coordinates, confidence, parsed evidence, prompt results, validation status, and repair context. It should not make every workflow understand raw provider payloads.

Diagnostics And Repair

Provider boundaries are most valuable when something goes wrong. Without a boundary, support sees only "the job failed" or "the API returned an error." With a boundary, support can ask better questions. Did authentication fail? Did the provider reject the payload? Was the request retried? Did we already write an external object? Did the response map to a known internal issue? Does an operator need to repair source data, or should the command be retried after provider recovery?

This is why provider results should be structured. A result can include external identifiers, idempotency keys, request context, response categories, retryability, validation errors, and user-facing diagnostics. The domain can then decide whether to advance, block, retry, or create an issue. The provider adapter does not own the business workflow, but it must provide enough evidence for the workflow to act safely.

Repair surfaces depend on this evidence. POA command repair, notification delivery diagnostics, accounting sync follow-up, geocoding review, and portal document recovery all need to distinguish provider failure from domain ambiguity. A provider timeout is not the same as an invalid invoice. A missing SharePoint file is not the same as a document precedence problem. A geocoding low-confidence result is not the same as a marketing suppression decision.

Reader Heuristics

When reading integration code, look for the handoff. If a domain route imports a provider client directly, the boundary is likely wrong. If a provider module decides domain workflow state, the boundary is also likely wrong. The healthy shape is external API to integration adapter, adapter to typed result, capability service to domain service, domain service to workflow state.

Also look for idempotency and diagnostics on outbound writes. Any provider operation that changes external state needs a way to avoid duplicate work and explain uncertain outcomes. This is especially important for accounting sync, document moves, email delivery, and command dispatch. A provider-boundary post should always answer what the platform can safely retry and what requires human review.

Finally, treat provider-specific pages as examples of this general pattern. Their value is not that every reader needs to know one provider API. Their value is that they show how the platform turns provider-specific behavior into reusable internal capability.

Public Writing Standard

Provider references are publishable when they teach the boundary pattern without becoming vendor implementation dumps. A useful public provider post should name the kind of provider, the internal capability it supports, the state or evidence the platform preserves, and the repair or diagnostic path. It should avoid assuming that the reader has credentials, raw payloads, or the codebase open.

That standard lets LKCI write about real integrations while still keeping the lesson general. A reader should come away understanding how to isolate provider messiness, not merely which endpoints a particular vendor exposes. This is also what makes provider pages useful as links from marketing, POA, finance, notifications, geo, and precon posts.

What Belongs In A Provider Reference

A provider reference should answer four practical questions. What outside system is being adapted? What internal capability does it support? What contract does the platform expose to the rest of the repo? What diagnostics exist when the provider behaves unexpectedly? That is enough for a technical reader to understand the boundary without reading credentials, raw payloads, or every provider endpoint.

The reference should also identify what the provider boundary intentionally does not own. A Microsoft integration may fetch documents or send mail, but it does not decide POA interpretation or morning brief policy. An email provider may deliver a message, but it does not own campaign suppression or audience membership. A trade or accounting provider may accept a sync command, but it does not own the human review state that made the command safe.

That distinction keeps provider writing useful to public readers. The lesson is how to isolate provider-specific behavior while preserving internal contracts, audit, and repair. The details can vary; the boundary discipline should not.

Source Evidence

  • integrations
  • services/data_sync
  • services/geocoding
  • services/notifications
  • services/auth
  • services/ocr
  • services/llm
  • docs/domains/data_sync.md
  • docs/domains/notifications.md
  • tests/integrations