# Repository Guidelines

## Project Structure & Module Organization

This Rust 2024 project is a KV-cache-aware proxy for OpenAI-compatible chat-completion backends.

- `src/main.rs`: Axum server setup and background cache vacuum worker.
- `src/config.rs`: validation and loading for `config.toml`.
- `src/cbr.rs` and `src/merkle.rs`: canonical prompt identity and Merkle block chain.
- `src/blockmap.rs`: block-to-backend replica locations, expiry deadlines, and vacuum heap.
- `src/router.rs`: cache-aware selection and atomic load reservations.
- `src/proxy.rs`: header-preserving streaming upstream proxy.
- `docs/adr/`: accepted architectural decisions; update these when changing durable design choices.
- `CONTEXT.md`: domain glossary; keep it free of implementation details.

Tests are co-located with implementation code in `#[cfg(test)] mod tests` blocks. Build artifacts belong under `target/`.

## Build, Test, and Development Commands

- `cargo build`: compile a debug binary.
- `cargo build --release`: build the optimized production binary.
- `cargo test`: run all unit and async tests.
- `cargo test router`: run tests whose names contain `router`.
- `cargo fmt --check`: verify Rust formatting; use `cargo fmt` to apply it.
- `cargo clippy --all-targets -- -D warnings`: enforce warning-free idiomatic Rust.
- `./target/release/kvca_proxy --config <PATH>`: run with a selected TOML file; omitting the option uses `config.toml`.

## Coding Style & Naming Conventions

Use four-space indentation and standard Rust naming: `snake_case` for functions and variables, `CamelCase` for types, and `SCREAMING_SNAKE_CASE` for constants. Group imports as `std`, external crates, then `crate::`, separated by blank lines. Prefer recoverable `Result` errors; reserve `expect` or `unwrap` for startup invariants and tests. Avoid unused public APIs and unrelated refactors.

## Testing Guidelines

Name tests `test_<scenario>`. Use `#[tokio::test]` for asynchronous routing, expiry, and proxy behavior. Non-trivial public behavior should have a happy-path test and an edge-case or failure-path test. Keep tests isolated and use short deterministic timeouts where lifecycle behavior is involved.

Before handing off changes, run formatting, the full test suite, strict Clippy, and a release build.

## Security & Configuration

Never commit credentials to `config.toml`. Request authorization and backend-specific end-to-end headers are forwarded upstream. Preserve hop-by-hop header filtering and avoid total timeouts that can truncate response streams.

## Commit & Pull Request Guidelines

No established Git history is available. Use imperative, capitalized commit subjects of about 50 characters; wrap bodies at 72 columns. PRs should explain the change, motivation, validation performed, and relevant trade-offs. Link issues and ADRs when applicable; screenshots are unnecessary unless user-visible output changes.