# Repository Guidelines

## Project Structure & Module Organization
- `src/` contains the crate root (`src/lib.rs`) and organ modules under `src/organs/`.
- Shared data types live in `src/types.rs`; domain errors in `src/error.rs`.
- FFI layer is `src/ffi.rs` with matching C header in `ffi/medicallib.h`; keep them aligned.
- Integration tests sit in `tests/` (run `cargo test --test patient` to target a file).
- Usage and tracing demos live in `examples/`; the C example is in `examples/c/`.
- Performance benchmarks use Criterion in `benches/` (see `benches/heart.rs`).
- Architectural and setup docs are at the repo root (`README.md`, `ARCHITECTURE.md`, `INSTALL.md`, `MIGRATION.md`).

## Build, Test, and Development Commands
- `cargo build` compiles the library in debug mode for fast iteration.
- `cargo build --release --features ffi` produces the shared library for FFI consumers.
- `cargo test` runs the full test suite; append `--test <name>` for a single integration test.
- `cargo run --example usage` or `cargo run --example tracing_demo` exercises examples.
- `cargo bench` executes Criterion benchmarks; compare results across runs in `target/criterion/`.
- `cargo clippy --all-targets -- -D warnings` enforces lint hygiene before committing.

## Coding Style & Naming Conventions
- Use `cargo fmt --all` (4-space indent, ~100-char lines) before sending patches.
- Modules and files use `snake_case`; types and traits use `CamelCase`; constants are `SCREAMING_SNAKE_CASE`.
- Favor standard library and existing crates; document any `unsafe` with clear safety notes.
- Keep public APIs cohesive within `src/organs/`; update examples/docs when the FFI surface changes.

## Testing Guidelines
- Prefer integration coverage in `tests/`; create files named after features (e.g., `tests/ffi.rs`).
- Add focused unit tests near code under `#[cfg(test)]` for invariants.
- Ensure tests are deterministic; avoid sleeps or external I/O without guards.
- Run `cargo test` and `cargo clippy` locally before opening a PR.

## Commit & Pull Request Guidelines
- Write imperative commit subjects (e.g., “Add heart rate update clamp”); Conventional Commits are welcome.
- PRs should link related issues, call out breaking changes, and mention new tests or examples.
- Include reproduction steps or screenshots only when they clarify user-facing changes.

## Security & FFI Notes
- Any change to `src/ffi.rs` must be mirrored in `ffi/medicallib.h` and validated against `examples/c/ffi_example.c`.
- Avoid introducing new runtime dependencies; discuss first if unavoidable.