# Nyro AI Gateway ## Purpose Nyro is a Rust workspace for a local AI protocol gateway with a Tauri desktop app, standalone server, and React WebUI. It translates OpenAI / Anthropic / Gemini-compatible client traffic to configured model providers while keeping administration and configuration local. ## Key Files | File | Description | |------|-------------| | `Cargo.toml` | Root `nyro` package plus workspace definition for the new data-plane crates and legacy applications. | | `Cargo.lock` | Locked Rust dependency graph. | | `README.md` / `README_CN.md` | User-facing project documentation in English and Chinese. | | `Makefile` | Common development and release commands. | | `docs/design/architecture.md` | Architecture overview and module layout. | | `webui/package.json` | React/Vite WebUI dependencies and scripts. | ## Subdirectories | Directory | Purpose | |-----------|---------| | `src/` | Experimental source-built root `nyro proxy` entrypoint, bootstrap, and Unix SIGHUP configuration reload; separate from released legacy entries. | | `crates/nyro-kernel/` | Workload-neutral lifecycle/generation library used by the experimental root proxy. | | `crates/nyro-protocol/` | Protocol wire types and bounded stream framing for the new data plane. | | `crates/nyro-llm/` | New typed LLM runtime, OpenAI/Anthropic/Gemini Chat codecs/providers, request execution, and correlated usage observations. | | `crates/nyro-config/` | Strict standalone file configuration for the experimental root proxy. | | `crates/nyro-security/` | Transport-neutral credential authentication and authorization primitives. | | `crates/nyro-limit/` | Shared concurrency, token-bucket rate admission, and cumulative quota primitives. | | `crates/nyro-core/` | Core Rust library: gateway, proxy, protocol conversion, provider adapters, storage, admin service. | | `crates/nyro-tools/` | Rust CLI/tooling crate. | | `src-server/` | Standalone server binary exposing proxy/admin HTTP surfaces. | | `src-tauri/` | Tauri desktop application shell and IPC integration. | | `webui/` | React + TypeScript management console. | | `docs/` | Design, server, standalone, and testing documentation. | | `tests/` | Python/E2E test assets and shared fixtures. | | `scripts/` | Install and release automation. | ## For AI Agents ### Working In This Repository - Keep changes focused and reversible; do not mix unrelated cleanup into feature or refactor work. - Prefer existing patterns and utilities before adding abstractions or dependencies. - Do not edit generated build output such as `webui/dist/` unless the task explicitly requires it. - Preserve separate English and Chinese user-facing docs when updating public documentation. ### Multilingual Defaults - For any multilingual/i18n-capable value, the default must be English, in both frontend and backend code. - This applies to UI labels, fallback strings, seed/default configuration, generated examples, API defaults, and documentation-derived constants. - Add localized alternatives explicitly, but keep the canonical fallback/default value in English unless a caller/user setting selects another language. ### Testing Requirements - Rust core changes: run the narrowest relevant `cargo test -p ...`, then `cargo check -p ` or `cargo clippy -p --all-targets` when behavior or public APIs change. - WebUI changes: run the relevant package script from `webui/` such as `npm run lint` or `npm run build` when TypeScript/UI behavior changes. - Documentation-only changes should still be checked for path/name accuracy. ### Common Patterns - `nyro-kernel` owns resource/generation invariants only; keep business rules, configuration, HTTP, databases, and global module discovery outside it. See its README for lifecycle ownership and cancellation contracts. - `nyro-core` should remain transport-agnostic; desktop IPC and server HTTP layers call into core APIs rather than embedding core business logic. - Admin service code should be split by functional responsibility and tested through public APIs where possible; keep private state-machine tests internal instead of exposing private APIs just for tests. - Protocol/provider logic should keep protocol conversion boundaries explicit and avoid coupling provider adapters to UI/server transport concerns. ## Dependencies ### Internal - The root `nyro` package composes `nyro-kernel`, `nyro-config`, `nyro-llm`, `nyro-security`, and `nyro-limit` for the experimental file-config proxy. - `src-tauri/` and `src-server/` depend on `crates/nyro-core/`. - `webui/` talks to the desktop IPC/server admin surfaces and should not duplicate core business rules. - Documentation in `docs/` should reflect current crate and module boundaries. ### External - Rust workspace uses Tokio, Axum, Reqwest, SQLx, Serde, Tauri, and tracing-related crates. - WebUI uses React, Vite, TypeScript, Radix UI primitives, TanStack Query, and Zustand. ### Database Changes When modifying the database schema — including changes to `INIT_SQL`, `POSTGRES_INIT_SQL`, `MYSQL_INIT_SQL` constants or the `migrate()` function in any storage backend — you **must** also: 1. Update `docs/database/schema.md` to reflect the new table/column definitions. 2. Regenerate `deploy/schema/postgres.sql` and `deploy/schema/mysql.sql` to match the final post-migration state: ```bash nyro-tools dump-schema --backend postgres > deploy/schema/postgres.sql nyro-tools dump-schema --backend mysql > deploy/schema/mysql.sql ``` These files are the authoritative reference schema for DBAs. They represent the **final state** after all migrations have run (with final table names: `models`, `model_backends`, `api_key_models`). > The SQL files in `deploy/schema/` are derived reference artifacts — do not manually edit them except to update the header comment. Always regenerate from the migration source of truth. ### Release Process Local release work (cutting a `release/vX.Y.Z` branch off `master` through pushing it): 1. Branch: `git checkout master && git pull && git checkout -b release/vX.Y.Z`. 2. Bump the version in **3 places** (keep identical): `Cargo.toml` `[workspace.package].version`, `src-tauri/tauri.conf.json` `version`, `webui/package.json` `version`. Refresh `Cargo.lock` via `cargo update -w` (never edit it by hand). 3. Changelog: summarize all commits since the last tag (`git log $(git describe --tags --abbrev=0)..HEAD --no-merges --oneline`) into a new version entry, and write it to **both** `CHANGELOG.md` (English, canonical) and `CHANGELOG_CN.md` (Chinese). 4. Verify with `make check` and `make test`, then commit (`chore: release vX.Y.Z`) and push the branch. PR merge (`release/vX.Y.Z` → `master`) and tagging `vX.Y.Z` are done remotely on GitHub; pushing the tag triggers the release workflows. > See `docs/release.md` for the full local release runbook (source of truth).