Messy Edge, Typed Inside

Summary

Provider APIs can be messy at the edge, but internal platform code should see normalized, typed contracts wherever possible.

Problem

External systems return inconsistent payloads, optional fields, changing enums, and provider-specific error behavior. If those shapes flow inward, every service and job becomes provider-aware.

Principle

Let integrations absorb provider mess, then normalize aggressively before data reaches services, jobs, review surfaces, or shared libraries.

Platform Shape

The architecture docs define integrations as external adapters and services as capability boundaries. Shared typed contracts belong in libs/ when multiple consumers need them. Services should not call raw provider clients unless they own a clear adapter boundary.

Source Evidence

  • docs/reference/architecture.md
  • integrations
  • libs
  • services
  • docs/engineering/reference/servicetitan-integration.md
  • docs/engineering/reference/quickbooks-online-integration.md