# Repository Guidelines
## Project Structure & Module Organization
- `src/lib.rs` exposes the crate API and coordinates the recorder, database handle, and initialization helpers.
- `src/{metrics_db,models,schema}.rs` wrap Diesel connections, models, and generated schema definitions.
- `src/recorder.rs` hosts the `SqliteRecorder` implementation that accepts events from the `metrics` crate.
- `examples/` contains feature-gated utilities; e.g., `cargo run --example export_csv --features export_csv`.
- `migrations/` stores Diesel migrations applied on startup; update these folders and regenerate `schema.rs` after schema edits.
## Build, Test, and Development Commands
- `cargo build` compiles the crate with default features.
- `cargo test` executes unit and integration suites; set `RUST_LOG=debug` to trace recorder behavior.
- `cargo fmt --all` enforces rustfmt style.
- `cargo clippy --all-targets -- -D warnings` surfaces lints that would fail CI.
- `cargo doc --no-deps` validates public documentation.
## Coding Style & Naming Conventions
Use standard Rust 2018 style: four-space indentation, `snake_case` for items, and `UpperCamelCase` for types. Feature flags (`export_csv`, `import_csv`) stay lowercase with underscores. Keep Diesel interactions in database modules, instrument critical flows with `tracing`, and run `cargo fmt` plus `cargo clippy` before review.
## Testing Guidelines
Add unit tests beside implementations with `#[cfg(test)]`, and use `tests/` for integration scenarios that exercise migrations or recorder flows. Tests should create temporary SQLite files instead of mutating `metrics.db`. Cover new metric types, error branches, and migration behavior. When touching shared code, run `cargo test --features export_csv,import_csv`.
## Commit & Pull Request Guidelines
Match the Conventional Commits style visible in history (`feat:`, `chore:`, `refactor:`). Squash fixups before review, and update `changelog.md` plus `Cargo.toml` when shipping releases. PRs should include a short summary, linked issues, manual testing notes, and screenshots or sample CSV output when behavior changes. Confirm `cargo fmt`, `cargo clippy`, and `cargo test` before requesting review, calling out any skipped checks.
## Migration & Configuration Tips
Schema changes need a new timestamped Diesel migration (`diesel migration generate <name>`), updates under `migrations/`, and a regenerated `schema.rs` (`diesel print-schema > src/schema.rs`). SQLite is bundled via `libsqlite3-sys`, so no external setup is required. When embedding in apps, set flush intervals and retention windows explicitly to prevent unbounded metric growth.