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
   core pipeline

   Modules

   crates/proxai-core/src/pipeline/src/pipeline/

   Responsibility

   Compose structured ingress, routing, translation, and provider adaptation in core while the app owns HTTP carriers and transport.

2. 2
   ingress

   Modules

   src/pipeline/inbound.rscrates/proxai-core/src/ingress/

   Responsibility

   Detect inbound protocol and parse HTTP bytes in the application adapter, then normalize and validate structured payloads in core.

3. 3
   routing

   Modules

   src/config.rscrates/proxai-core/src/pipeline/

   Responsibility

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

4. 4
   translation

   Modules

   crates/proxai-core/src/translation/

   Responsibility

   Convert protocol payloads and streams without HTTP carriers; legal adaptations emit typed observations.

5. 5
   provider

   Modules

   crates/proxai-core/src/provider/src/provider/*/requestsrc/provider/*/transport

   Responsibility

   Prepare structured provider values in core, then project, serialize, authenticate, and send them in the application.

6. 6
   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/pipeline/inbound.rs

Inbound HTTP path/protocol detection, JSON byte parsing, and application error mapping.

crates/proxai-core/src/pipeline/

Carrier-independent request/response composition façade and request-scoped core observer binding.

crates/proxai-core/src/ingress/

Carrier-independent request normalization, protocol validation, model extraction, and typed ingress observations.

crates/proxai-core/src/observe.rs

Shared `Observer` contract, closed `Observation` variants, and no-op default.

crates/proxai-core/src/protocol/

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

crates/proxai-core/src/translation/

Carrier-independent protocol-to-protocol payload and stream conversion across explicit pairs, with typed adaptation observations.

crates/proxai-core/src/provider/

Carrier-independent provider request value preparation, structured response/error normalization, and typed adaptation observations.

src/provider/*/request

Provider logging projection/summary extraction, outbound payload serialization, and request carrier assembly.

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.Testing PhilosophyWhy regression tests are physically separated, and the failure trust gradient between real-world and synthetic tests.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.