Where to Change Code

Where to Change Code

Use this page as a maintainer routing map. It points common change requests to the source owners, validation paths, and documentation that should move with the code.

Code is the source of truth

Documentation follows implementation and verified behavior. If docs and code disagree, inspect the implementation, tests, and config.example.toml first, then update code or docs deliberately.

Change routing map

Runtime setting

Start in `src/config.rs`; update `config.example.toml`, wiring in `src/main.rs` or `src/lib.rs`, user docs, reference docs, and config-loading tests.

Inbound protocol parsing

Use `src/pipeline/inbound.rs` for HTTP path/body adaptation, `crates/proxai-core/src/ingress/` for structured normalization/validation, and `crates/proxai-core/src/protocol/` for wire shapes.

Route matching

Start in `crates/proxai-core/src/routing/`; preserve strict `request_protocol` guard behavior and avoid silent fallthrough for mismatched explicit guards.

Provider request behavior

Use `crates/proxai-core/src/provider/request/` for structured value preparation, model rewrite, provider-local adaptation, and typed observations; use `src/provider/*/request` for logging projections/summaries and JSON serialization.

Provider response/error compatibility

Use `crates/proxai-core/src/provider/` for structured payload/event repair, error-payload normalization, and typed observations; keep status, headers, body bytes, and rendering in the application.

Provider transport

Start in `src/provider/*/transport`; keep auth headers, upstream URL construction, and HTTP send behavior outside pure translation.

Protocol conversion

Start in `crates/proxai-core/src/translation/`; keep request/response/stream conversions pure at the carrier boundary.

Streaming semantics

Start in SSE scanner, streaming translation modules, and provider response observers; preserve terminal events, Unicode safety, and tool-call stall handling.

Client-facing errors

Start in `src/error/`; keep stable compact error projection and safe preserved upstream headers.

Capture/logging

Start in `src/observe/`; keep logs compact, structured, body-safe, and phase names aligned with reference docs.

Task checklist

1. 1

   Add or change a runtime config field

   Goal: Keep runtime configuration centered on config.toml and its tracked example.

   Do

   • Update src/config.rs.
   • Add a concise example/comment to config.example.toml.
   • Wire through startup/runtime state only where needed.
   • Update using/configuration and reference/configuration.
   • Add or adjust config loading/default tests.

   Verify: just site check and relevant Rust config tests agree with the new default and docs.

   Config FlowConfiguration Reference
2. 2

   Add a protocol conversion path

   Goal: Preserve explicit pair-oriented translation.

   Do

   • Add request conversion only if inbound → provider request behavior is supported.
   • Add non-streaming response conversion if provider → inbound response behavior is supported.
   • Add streaming conversion separately; do not assume non-streaming support implies stream support.
   • Update compatibility docs and behavior tests.

   Verify: Unsupported pairs fail explicitly; supported pairs have behavior coverage for payloads and stream terminal semantics.

   Protocol ConversionCompatibility Matrix
3. 3

   Fix a streaming regression

   Goal: Preserve bytes, event order, terminal detection, and semantic timeouts.

   Do

   • Reproduce with the smallest stream fixture.
   • Identify whether the failure is carrier, SSE event semantics, protocol conversion, or client-facing reconstruction.
   • Add coverage for terminal events, incomplete tool streams, stalled tool-call arguments, or Unicode chunk boundaries as appropriate.

   Verify: Targeted streaming tests pass before broader e2e validation.

   Streaming InternalsStreaming Behavior
4. 4

   Change error rendering

   Goal: Keep errors compact, stable, safe, and useful.

   Do

   • Map internal errors to stable client-facing types.
   • Preserve useful safe upstream headers such as Retry-After.
   • Avoid leaking private bodies, auth headers, API keys, or private prompts.
   • Update reference error types and behavior contracts.

   Verify: HTTP and SSE error behavior are both covered when stream state matters.

   Error FlowError Responses

Source ownership table

If you are changing	Primary source area	Also check
CLI flags	src/cli/	README.md, README_CN.md, reference/cli
Generated app-directory defaults	src/paths.rs, config loading code	config.example.toml, config tests
Route protocol guards	crates/proxai-core/src/routing/	reference/route-matching, core routing tests, proxy e2e route tests
Provider model rewrite or request-value adaptation	crates/proxai-core/src/provider/request/	src/provider/*/request, provider setup docs, compatibility matrix, and core observations
Provider response/error compatibility	crates/proxai-core/src/provider/	src/error/upstream.rs, provider response pipeline/SSE tests, provider docs, and core observations
Anthropic wire structs	crates/proxai-core/src/protocol/anthropic/	SDK alignment docs and conversion tests
OpenAI Responses wire behavior	crates/proxai-core/src/protocol/openai/responses/	Responses protocol docs and conversion tests
Capture phase names	src/observe/ and flow locals	reference/capture-phases, docs checker phase coverage
Docs IA or bilingual pages	site/src/content/docs/	tools/check_docs_i18n.py, developer/docs-maintenance

Validation order

Prefer the smallest validation that covers the changed boundary, then move outward. For documentation-only work, run just site check. For runtime behavior, use the project validation guidance in AGENTS.md and the relevant test recipes.