Integration Architecture

No enterprise service lives alone. Even a well-bounded Carrier service will usually depend on identity systems, data platforms, third-party APIs, legacy applications, messaging infrastructure, reporting systems, and other internal services.

External Clients

Carrier supports typed external clients. The hello-carrier example imports a gRPC inventory service from a proto file, with bearer auth, deadlines, and retry configuration declared inline:

client InventoryGrpc {
proto: "./protos/inventory.proto"
service: "Inventory"
endpoint: env("INVENTORY_GRPC", "http://127.0.0.1:50051")
auth: bearer(env("INVENTORY_TOKEN", "dev-token"))
deadline_ms: 1200
retries: 2
}

A client boundary should hide the remote system's technical details from the domain logic. Actions should not be filled with low-level HTTP mechanics, credential handling, response parsing, and vendor-specific error interpretation. Those details belong near the client integration layer.

Service-to-Service APIs

Service-to-service APIs are the standard integration path when one internal domain needs another's capability. Even when APIs are not public, they are still contracts. Internal consumers can break just as real users can. A good service-to-service API should expose business capability, not database structure.

Event-Driven Integration

Events are useful when other systems need to react to something that happened without tightly coupling to the source service's request path. An event should represent a fact — PatientRegistered, EncounterClosed, ClaimSubmitted, ConsentRevoked, InvoiceApproved — not merely a remote procedure call in disguise. A useful rule: emit events for meaningful domain facts, not for every internal data mutation.

Legacy System Boundaries

Most enterprises have legacy systems that cannot simply be replaced. Carrier services often need to coexist with these systems during migration or modernization. A legacy boundary should be explicit. The Carrier service should make clear whether the legacy system is the current source of truth, a downstream consumer, a temporary synchronization partner, a read-only reference source, or a system being gradually replaced.