Add a port adapter

Ports-and-adapters is the product's core architecture (see Ports and adapters). This tutorial adds an adapter for a capability that already has a port — e.g. a new transcription engine or storage backend.

PrerequisitesCopy Anchor Link

• Understand the port interface you are implementing — it lives in a packages/<domain> package (e.g. packages/transcription defines Transcriber).
• The dev environment set up.

StepsCopy Anchor Link

1. Read the port. Find the interface in the domain package. Note what the port promises (events, capabilities like supported, optional hooks such as sessionStats()/recording()).

2. Create the adapter package. Follow the sibling convention — e.g. packages/transcription-whisper and packages/transcription-webspeech are two adapters for the same Transcriber port. Create packages/<capability>-<vendor>/.

3. Implement the interface exactly. Adapters live at the edge: they may use node:*, vendor SDKs, and provider literals — that's their job. Keep domain types from the port; don't leak vendor shapes upward.

4. Wire selection at the composition root. Which adapter runs is decided where the app is assembled (apps/web route composition / driver registries), never inside plugins. Look at how the transcription driver registry selects whisper vs webspeech.

5. Test the adapter in isolation. Unit-test against the port contract; the arch lint will fail the build if adapter code leaks into ports/plugins.

VerifyCopy Anchor Link

• bun run check and package-scoped bunx vitest run pass.
• The feature works end-to-end with your adapter selected, and still works with the previous adapter — that's the point of the port.