Developer Guide

Developer Guide

This section is for maintainers changing ProxAI internals. It focuses on source-level boundaries, protocol conversion rules, streaming behavior, and error projection.

Internal docs

These pages describe implementation boundaries. User-facing behavior belongs in Using ProxAI, Protocol Guide, and Reference.

Core boundaries

1. 1
   ingress

   Modules

   src/ingress/src/protocol/

   Responsibility

   Detect inbound protocol, parse payloads, and normalize inbound request shape.

2. 2
   routing

   Modules

   src/config.rspipeline routing

   Responsibility

   Select provider by protocol-aware defaults or explicit model routes.

3. 3
   translation

   Modules

   src/translation/

   Responsibility

   Convert protocol payloads and streams across pure protocol boundaries.

4. 4
   provider

   Modules

   src/provider/*/requestsrc/provider/*/transport

   Responsibility

   Prepare provider request payloads, rewrite models, add provider auth, construct upstream URLs, and send.

5. 5
   response reconstruction

   Modules

   src/http_supportsrc/error/

   Responsibility

   Translate responses back to the inbound protocol and render compact client-facing errors.

Source tree map

src/ingress/

Inbound HTTP path/protocol detection, request parsing, and normalization before routing.

src/protocol/

Wire data models for OpenAI Responses, OpenAI Chat Completions, Anthropic Messages, and SSE payloads.

src/translation/

Pure protocol-to-protocol payload and stream conversion across explicit pairs.

src/provider/*/request

Provider request preparation, projection, provider model rewrite, and outbound payload serialization.

src/provider/*/transport

Upstream URL construction, provider authentication headers, and HTTP send behavior.

src/provider/*/response

Provider response summaries, streaming observers, protocol state machines, and outcome diagnostics.

src/http_support/

HTTP carrier helpers for response header/body reconstruction and byte streams.

src/error/

Typed internal errors and compact client-facing HTTP/SSE error rendering.

src/observe/

Structured logs, request hints, duration coloring, and capture-safe diagnostics.

Pages

ArchitectureRequest lifecycle, module boundaries, pipeline phases, and how protocol translation fits into the proxy.Request LifecycleSource-level path from inbound request through provider transport to outbound response.Protocol ConversionPair-oriented conversion rules, wire-model alignment, SDK comparison, and streaming identifier models.Streaming InternalsCarrier, BodyObserver, SSE scanner, and protocol state machines.Error Handling InternalsTyped errors, ErrorResponseSpec, fields, payload, and HTTP/SSE rendering.Where to Change CodeTask map for source owners, tests, validation, and docs that move with implementation changes.Test MapValidation guide for config, routing, translation, streaming, errors, capture, and docs changes.Contributor ChecklistOperational checklist for runtime settings, conversion pairs, streaming, errors, tests, and docs.Docs MaintenanceRules for doc ownership, bilingual pages, MDX components, validation, and source-of-truth boundaries.

Change map

New runtime setting

Update src/config.rs, config.example.toml, user docs, reference docs, and tests for generated defaults.

Where to change code

Use the task-oriented source map before touching routing, provider, translation, streaming, error, capture, or docs internals.

Test map

Choose the narrowest validation command first, then expand for user-visible proxy or streaming behavior.

New conversion pair

Add request/response/streaming conversion, route support, behavior tests, and protocol docs.

Streaming change

Check carrier semantics, SSE terminal events, tool-call stalls, Unicode chunk scanning, and e2e tests.

Error rendering change

Update error projection, preserved headers, SSE error behavior, and behavior contracts.