tiygate AGENTS.md

Repository Guidelines

Contributor guide for TiyGate, an open-source Rust AI Gateway. Preserve the crate layering described below; it is intentional and enforced.

Project Structure & Module Organization

This repository is a Cargo workspace with 8 crates and an embedded admin console:

• crates/core contains canonical IR, traits, and pipeline code. It must stay zero-I/O and free of concrete provider, protocol, or database dependencies.
• crates/protocols implements protocol codecs for chat completions, messages, responses, Gemini, and embeddings.
• crates/providers stores built-in provider metadata and auth; crates/provider-bedrock isolates heavy AWS Bedrock SDK dependencies.
• crates/store, crates/cache, crates/admin, and crates/server cover config storage, embedding cache, Admin REST/OAuth, and the tiygate binary.
• webui/ is the React + TypeScript + Vite admin console, embedded with rust-embed and served at /admin/ui.
• docs/ holds architecture and protocol capability docs; scripts/ contains helper checks such as verify-deps.sh.
• Tests live in crates/<crate>/tests/ for integration tests and inline #[cfg(test)] modules for unit tests.

Engineering Principles

Keep changes aligned with three project constraints:

• Reliability first: keep the request hot path resilient with fallback budgets, circuit breakers, ingress limits, graceful drain, and telemetry/logging off the hot path.
• Extensible by design: add providers, protocols, routing strategies, cache backends, and log sinks through existing trait/registration boundaries instead of central rewrites.
• Maintainable layering: keep core as canonical IR + traits only, use the IR to avoid N×N protocol coupling, document lossy protocol behavior in docs/protocol-capability-matrix.md, and isolate heavy dependencies in dedicated crates.

Build, Test, and Development Commands

Run commands from the repository root. Use make help for the full list.

make build        # Build webui, then release Rust binary
make build-debug  # Build webui, then debug Rust binary
make dev          # Build webui and run tiygate-server with webui feature
make dev-server   # Run Rust server only, without webui embedding
make dev-web      # Start the WebUI Vite dev server
make check        # cargo check --workspace --all-targets --all-features
make test         # cargo test --workspace --all-features
make lint         # rustfmt check, clippy -D warnings, and webui tsc
make fmt          # Format Rust and WebUI code
make audit        # Run cargo audit and npm audit