Architecture and dependency rules
The SDK is organized so domain code depends on small interfaces and portable value types, while infrastructure remains at the edge.
Package roles
- platform/config, platform/errors, platform/paging, and platform/security/identity are portable kernel contracts.
- platform/http adapts typed handlers to net/http and owns response rendering.
- platform/database/sql, platform/cache, and platform/events define interfaces and portable behavior.
- platform/database/sql/pgx, platform/cache/redis, and platform/events/amqp are named vendor adapters and escape hatches.
- platform/bootstrap is a composition root. No business package imports it.
Dependency direction
Business and application packages:
- may use context, domain types, and portable platform contracts;
- define narrow repository/client interfaces next to their consumer;
- do not import pgx, Redis, AMQP, router, cloud, or search clients.
Adapter packages implement those ports. cmd/server chooses implementations and owns concrete dependency construction.
What the SDK owns
The SDK owns behavior that must be uniform across services: configuration precedence, safe error rendering, identity context, route declarations, response envelopes, health, transaction propagation, event envelopes, cache semantics, worker supervision, and shutdown order.
It does not own domain rules, domain entities, service-specific SQL, service-specific event payloads, or orchestration between business capabilities.
Abstraction test
Add a reusable abstraction only when:
- at least two real consumers need the same semantic contract;
- the API reduces policy variation rather than hiding useful behavior;
- failure, lifecycle, and observability semantics are explicit;
- an escape hatch exists for operations the contract should not absorb;
- focused tests prove both the interface and primary adapter.
See Extension points before expanding the SDK.