Keep provider SDK types out of appointment rules
Rescheduling logic imports provider B's request object and recognizes its numeric error codes. A provider SDK change now forces changes in domain tests that never make a network request.
- Focused work estimate
- 2h 30m + prerequisites
- Priority in the scenario
- Medium
- Engineering practice
- Dependency inversion · Module boundaries · Contract testing
Estimated field mix
- Integrations50%
- System design50%
Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence.
Pattern topics
- Ports and AdaptersApply
Move vendor request types and error codes behind a domain-owned notification port so scheduling rules can run without initializing transport code.
Review it, then add it to your workspace.
The board opens an editable draft; nothing is saved until you confirm it. Sign-in and workspace permissions apply, and Demo boards remain ephemeral.
Project context
A fictional maintenance scheduler sends appointment notices through two providers. Their request shapes, error codes, and acknowledgement semantics differ. Build two local scripted provider doubles and a TypeScript application module; use synthetic recipients, block external network access, and never send real notifications. No provider accounts, starter repository, or production delivery qualification is supplied.
Setup prerequisites
- HTTP contracts
- Asynchronous cancellation
- Dependency injection
Preceding work
Complete these dependencies, or supply their agreed outputs before taking this ticket.
Acceptance criteria
- Appointment logic depends on a small notification port using domain-owned request and result types.
- Place provider-specific mapping, serialization, and error interpretation in adapters selected at the composition boundary.
- Run appointment decisions against an in-memory port double with no provider package imports or transport initialization.
Implementation constraints
- Keep this a module boundary in one process; the exercise does not justify splitting the application into services.
Verification to include
- Replace A with B through composition wiring and run the same appointment behavior cases.
- Make the port return rejected and unknown outcomes and verify the domain does not treat either as successful acceptance.
Deliverables
- Domain notification port and provider-free appointment tests
Rollout and recovery
Migrate one appointment use case to the port, compare results, then migrate the remaining local caller; revert adapter wiring if parity fails.
Value of the work
For the engineer: Practice placing provider boundaries, comparing wrappers and coordinators, and testing ordering, cancellation, and resource limits under controlled faults.
For the team: Review whether a provider change can be made without rewriting scheduling rules, leaking recipient data, or turning one provider failure into wider exhaustion.
Evidence boundaries
Outcome Evidence: Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.
Ownership Evidence: Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence.