Why can’t PlatformKit business modules import each other?

[discitte]

Why does PlatformKit declare module dependencies through typed ports instead of importing and constructing another module’s concrete implementation directly? How does that work during composition?

[joaorufino]

In summary platformKit separates a module’s capability from its implementation.

A module advertises a capability using a typed Go interface:

module.Provide[AuditService]("1.0.0")

While a consumer declares what it needs:

  module.RequiresPort[AuditService](module.PortSpec{
      Version:           "^1.0.0",
      Purpose:           "record domain mutations",
      PreferredProvider: "audit_management",
  })

The composition layer then validates and orders the graph before starting the application. It checks that:

• Every required port has a compatible provider.
• Provider versions satisfy the requested constraint.
• Preferred or explicitly allowed fallback providers are respected.
• Dependencies can be arranged without a cycle.
• Startup ordering is deterministic.

This avoids coupling a consumer to another module’s database, constructors, handlers, or private types. A different provider can satisfy the same contract without changing the consumer.

Required and optional ports also have distinct meanings. i.e. a missing required port prevents the application from booting. A missing optional port allows the module to operate with reduced functionality—for example, without an admin-page or health
registrar.

For synchronous behavior, use a narrow typed port. For asynchronous facts that several consumers may observe, use events or a transactional outbox. Product-specific workflows that coordinate several capabilities generally belong in the downstream application rather than inside a reusable module.

TLDR; The important point is that dependency injection supplies runtime values, while typed ports describe and validate the architectural graph. The compiler verifies the interface; composition verifies that the complete application is coherent.

Relevant code: pk-core/pkg/module