lxc-streamutils/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

apps/server-rust/ contains the Axum backend, live-event adapters, authentication, persistence, and WebSocket delivery. Database migrations live in apps/server-rust/migrations/; Rust unit and async tests are normally kept beside the modules they exercise. apps/overlay/src/ contains the React/Vite control and OBS interfaces, with PWA code in apps/overlay/pwa/ and static assets in apps/overlay/public/. Architecture, protocol, security, and component notes belong in docs/; deployment support lives in deploy/, Dockerfile, and compose.yaml. The backend uses the sibling ../libilibili checkout as a path dependency; coordinate API changes in that crate instead of copying it here.

Build, Test, and Development Commands

• cargo fmt --manifest-path apps/server-rust/Cargo.toml formats Rust code.
• cargo clippy --manifest-path apps/server-rust/Cargo.toml --all-targets --no-deps -- -D warnings runs strict Rust linting.
• cargo test --manifest-path apps/server-rust/Cargo.toml --all-targets runs backend tests.
• npm --prefix apps/overlay run dev starts the Vite development server.
• npm --prefix apps/overlay run format:check checks Prettier; use run format to apply it.
• npm --prefix apps/overlay run build type-checks and builds the frontend; run docs:check validates documentation links.
• docker compose config --quiet validates deployment configuration; docker compose up --build -d builds and starts the stack.

Run git diff --check before submitting changes.

Coding Style & Naming Conventions

Use four spaces in Rust and TOML, and two spaces in TypeScript, CSS, Markdown, JSON, and YAML. Rust uses snake_case for modules/functions and PascalCase for types. TypeScript uses camelCase for functions/values and PascalCase for React components and types. Let rustfmt and the pinned Prettier version decide layout. Do not bulk-format vendored code.

Testing Guidelines

Add Rust tests near the changed behavior using #[test] or #[tokio::test]. There is no fixed coverage threshold, but regressions and tenant-boundary behavior require tests. Frontend changes must pass formatting and production builds. For visual overlay work, manually verify representative OBS sizes and attach before/after screenshots to the pull request.

Commits, Pull Requests & Security

Follow existing history: use a short, lowercase, imperative or descriptive commit subject and keep each commit to one logical change. Pull requests should summarize behavior, list verification commands, note migrations or configuration changes, link relevant issues, and include screenshots for UI work.

Never commit config.toml, .env, CookieCloud credentials, TOTP secrets, recovery codes, session secrets, or OBS tokens; update examples with placeholders instead. Preserve tenant isolation, PostgreSQL RLS policies, and authenticated ownership checks in every query and API boundary.