Integrations And Workflow

Summary

Integrations are the edge adapters that let LKCI workflows use external systems without importing each provider's vocabulary into every page, job, and service. They are intentionally messy at the boundary and intentionally typed inward. This thread explains how provider-backed sync, accounting, document access, email delivery, geocoding, auth, OCR, and LLM capabilities fit into workflow architecture.

The main rule is simple: jobs, API routes, and review services should not speak directly to external APIs unless the integration boundary is itself the thing being implemented. Provider behavior should be normalized into internal contracts before it reaches a state machine or UI.

Reader Question

How do external systems participate in operational workflows without leaking provider-specific errors, credentials, pagination, identity models, or side effects into the rest of the platform?

Surface Or Workflow

The entry surface is usually indirect. An operator sees an accounting sync status, a SharePoint document, a Postmark delivery result, a geocoded address, an auth/module decision, or an OCR/LLM-derived artifact. The surface should show internal state and actionable diagnostics, not raw provider mechanics.

Support engineers enter through sync diagnostics, integration tests, runbooks, provider logs, and failed job artifacts. They need to know which layer owns the problem: provider adapter, capability service, domain state machine, job entrypoint, or UI/API mapping.

Lifecycle

The lifecycle starts at an external boundary: token, request, response, document, webhook, file, map lookup, or provider error. The integration module translates that boundary into internal records or typed values. A service then decides how the platform should use it: link an external object, publish sync state, render a notification, geocode a candidate, or attach evidence to a review workflow.

When the workflow writes outward, the same separation matters. A domain action may request a send, move, sync, or update, but the provider call should remain behind an integration or capability service. Retry, partial success, audit, and human repair should be modeled by the domain or shared workflow layer rather than hidden inside a provider client.

Child Threads

Implementation Boundaries

integrations/ owns provider-specific clients and edge translation. services/data_sync owns sync linkage and operational sync helpers. services/geocoding, services/notifications, services/ocr, services/llm, and services/auth expose reusable capabilities to state machines and jobs. Domain packages decide how external evidence affects business state.

tests/integrations is part of the evidence trail. It protects path handling, auth behavior, provider-specific parsing, paging, and error normalization so the rest of the platform can rely on stable internal semantics.

Tradeoffs

Integration boundaries add indirection. A developer may need to trace from a UI action to a service, then to an integration adapter, then to a provider response. That cost is preferable to letting provider quirks become platform architecture. The boundary also makes future provider swaps, replay, audit, and public-safe documentation easier.

Visual

The current visual is a graph neighborhood. The target visual is a provider boundary map: external API or artifact, integration adapter, typed internal contract, capability service, domain workflow, and support diagnostics.

Source Evidence

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