Module Boundaries

Module Boundaries

This page is a maintainer map for deciding where code belongs. When in doubt, keep protocol conversion explicit and keep provider-specific behavior out of generic translation.

Do not blur protocol and provider boundaries

Provider names are user labels. Protocol names describe wire behavior. A provider module may adapt local provider quirks, but general protocol-to-protocol shape changes belong in src/translation/.

Ownership map

src/ingress/

Detect inbound protocol from HTTP path, parse inbound body, normalize request carriers before routing.

src/protocol/

Wire structs, enums, and protocol-specific event payloads. No provider routing decisions.

src/routing/

Match request_protocol and model_pattern, select provider, enforce protocol guard errors.

src/translation/

Pure request/response/stream conversion between protocol pairs.

src/provider/*/request

Provider request preparation: model rewrite, provider compatibility projection, serialization.

src/provider/*/transport

Upstream URL construction, provider-owned auth headers, HTTP send.

src/upstream/

Read provider status, headers, non-streaming body, and streaming byte carriers.

src/http_support/

HTTP response reconstruction, content-type helpers, header filtering, byte stream carriers.

src/error/

Domain error taxonomy and compact client-facing error projection.

src/observe/

Structured logs, capture phases, hints, and privacy-aware diagnostics.

Boundary decisions

Question	Put it in
Does it parse a client request path or body?	src/ingress/
Does it define protocol JSON wire shape?	src/protocol/
Does it select a provider by protocol/model?	src/routing/ or pipeline routing step
Does it convert one protocol payload into another protocol payload?	src/translation/
Does it rewrite provider model or provider-local request fields?	src/provider/*/request
Does it add provider auth headers or build upstream URLs?	src/provider/*/transport
Does it filter headers or rebuild an HTTP response?	src/http_support/
Does it render client-facing errors?	src/error/
Does it write logs or capture artifacts?	src/observe/

Anti-patterns

Avoid	Why
Passing HTTP Response into src/translation/	Translation should stay pure at the carrier boundary.
Adding provider auth logic in translation	Auth is provider transport behavior, not protocol conversion.
Treating provider names as protocol values	Provider names are user labels and can be arbitrary.
Silently falling through after a protocol guard mismatch	A matching route with mismatched request_protocol is a configuration error.
Logging request bodies for convenience	Prompts, tool arguments, and outputs are private data.

Related docs

• Request Lifecycle
• Protocol Conversion
• Behavior Contracts
• Capture Phases