# Repository Guidelines

## Repository Overview
- Noteflow ships a Python backend (gRPC server + domain services) and a Tauri + React desktop client.
- The gRPC API is the shared contract between backend and client; schema lives in `src/noteflow/grpc/proto/noteflow.proto`.
- Backend code is layered: domain (pure models + ports), application (use-cases), infrastructure (IO implementations).
- The repo is split into backend package (`src/noteflow/`) and frontend app (`client/`), with tests and docs alongside.
- When you touch shared contracts (proto fields/enums, DTOs), update Python, Rust, and TypeScript counterparts together.

## Quick Orientation (Start Here)
- Backend entry point: `python -m noteflow.grpc.server` (service implementation in `src/noteflow/grpc/service.py`).
- Tauri/React client: `cd client && npm run dev` (web), or `npm run tauri dev` (desktop).
- Tauri IPC bridge: `client/src/api/tauri-adapter.ts` (TS) <-> `client/src-tauri/src/commands/` (Rust).
- Protobuf contract and generated stubs live in `src/noteflow/grpc/proto/`.

## Project Structure & Module Organization
- `src/noteflow/domain/` defines entities, value objects, and port protocols; keep this layer pure and testable.
- `src/noteflow/application/` hosts use-case services (Meeting, Recovery, Export, Summarization, Trigger, Webhook, Calendar, Retention, NER).
- `src/noteflow/infrastructure/` provides concrete adapters (audio, ASR, persistence, security, summarization, triggers, calendar, ner, observability, webhooks, converters).
- `src/noteflow/grpc/` contains the server, client wrapper, modular mixins (streaming/, diarization/ as packages), and proto conversions.
- `src/noteflow/cli/` provides CLI tools for retention management and model commands.
- `client/` is the Tauri/Vite React client; UI in `client/src/`, Rust shell in `client/src-tauri/`, e2e tests in `client/e2e/`.

## Backend Architecture & Data Flow
- gRPC server entry point lives in `src/noteflow/grpc/server.py`; `NoteFlowServicer` in `src/noteflow/grpc/service.py` composes feature mixins.
- Proto <-> domain conversions and enum mappings are centralized in `src/noteflow/grpc/_mixins/converters.py`.
- Unit-of-work and repositories live under `src/noteflow/infrastructure/persistence/`, with memory fallback when no DB is configured.
- Streaming audio ingestion uses `src/noteflow/infrastructure/audio/` and ASR/VAD components in `src/noteflow/infrastructure/asr/`.
- Encryption, key storage, and secure asset handling live in `src/noteflow/infrastructure/security/`.

## Client Architecture (Tauri + React)
- React components are in `client/src/components/`, custom hooks in `client/src/hooks/`, and shared types in `client/src/types/`.
- API layer lives in `client/src/api/` with adapters (`tauri-adapter.ts`, `mock-adapter.ts`, `cached-adapter.ts`) and connection management.
- React contexts are in `client/src/contexts/` (e.g., `connection-context.tsx` for gRPC state).
- Tauri command calls are in `client/src/api/tauri-adapter.ts`; Rust command handlers live in `client/src-tauri/src/commands/`.
- Rust app entry points are `client/src-tauri/src/main.rs` and `client/src-tauri/src/lib.rs`; shared state lives in `client/src-tauri/src/state/`.
- Rust gRPC client is organized under `client/src-tauri/src/grpc/` with `client/` and `types/` subdirectories.
- Client tests are colocated with UI code (Vitest) and end-to-end tests live in `client/e2e/` (Playwright).

## Contracts & Sync Points (High Risk of Breakage)
- Source-of-truth API schema: `src/noteflow/grpc/proto/noteflow.proto`.
- Python gRPC stubs are checked in under `src/noteflow/grpc/proto/`; regenerate them when the proto changes.
- Rust/Tauri gRPC types are generated at build time by `client/src-tauri/build.rs`; keep Rust types aligned with proto changes.
- Frontend enums/DTOs in `client/src/types/` mirror proto enums and backend domain types; update together to avoid runtime mismatches.
- When adding or renaming RPCs, update server mixins, `src/noteflow/grpc/client.py`, Tauri command wrappers, and `client/src/api/tauri-adapter.ts`.

## Common Pitfalls & Change Checklist

### Proto / API evolution
- Update `src/noteflow/grpc/proto/noteflow.proto` first; treat it as the schema source of truth.
- Regenerate Python stubs under `src/noteflow/grpc/proto/` and verify imports in `src/noteflow/grpc/`.
- Update gRPC server mixins in `src/noteflow/grpc/_mixins/` and service wiring in `src/noteflow/grpc/service.py`.
- Update the Python client wrapper in `src/noteflow/grpc/client.py`.
- Update Tauri/Rust command handlers in `client/src-tauri/src/commands/` and any Rust gRPC types.
- Update TypeScript adapters in `client/src/api/tauri-adapter.ts` and DTOs/enums in `client/src/types/` and `client/src/api/types/`.
- Add or adjust tests in both backend and client to cover payload changes.

### Database schema & migrations
- Update ORM models and add Alembic migrations under `src/noteflow/infrastructure/persistence/migrations/`.
- Review autogenerated migrations before applying; keep them deterministic and reversible.
- Update repository and UnitOfWork implementations when introducing new tables/relationships.
- Keep export/summarization converters in `src/noteflow/infrastructure/converters/` aligned with schema changes.

### Client sync points (Rust + TS)
- Tauri command signatures in `client/src-tauri/src/commands/` must match TypeScript calls in `client/src/api/tauri-adapter.ts`.
- Rust gRPC types are generated by `client/src-tauri/build.rs`; verify proto paths when moving files.
- Frontend enums in `client/src/types/` and `client/src/api/types/` mirror proto enums; update both sides together.

## Build, Test, and Development Commands
- Backend setup/run: `python -m pip install -e ".[dev]"`, `python -m noteflow.grpc.server`.
- Backend checks: `pytest`, `pytest -m "not integration"`, `ruff check .`, `ruff check --fix .`, `mypy src/noteflow`.
- Frontend dev/test: `cd client && npm run dev`, `npm run build`, `npm run test`, `npm run typecheck`.
- Frontend lint/format: `cd client && npm run lint`, `npm run lint:fix`, `npm run format`, `npm run format:check`.
- Rust checks: `cd client && npm run lint:rs` (clippy), `npm run format:rs` (rustfmt); install tools via `rustup component add rustfmt clippy`.
- Packaging: `python -m build`.

## Makefile, Hygiene Output, and Code Quality Standards
- The Makefile is the source of truth for repo-wide code quality checks; use targets there before adding ad-hoc commands.
- Linter/type-checker outputs are written to `./.hygeine/` for review and troubleshooting.
- Keep Makefile targets flexible: they accept optional file or directory arguments in addition to repo-wide defaults.
- Never modify linter configurations (e.g., Ruff/Biome/ESLint/Pyrefly/Clippy/Prettier configs) unless the user explicitly requests it.
- Linting and type checking must stay strict: no relaxing rules, no suppressing warnings, no removing checks.

## Coding Style & Naming Conventions
- Python 3.12 with 4-space indentation and 100-character line length (Ruff).
- Naming: `snake_case` for modules/functions, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
- Keep typing explicit and compatible with strict `mypy`; generated `*_pb2.py` files are excluded from lint.
- Frontend formatting uses Prettier (single quotes, 100 char width); linting uses Biome.
- Rust formatting uses `rustfmt`; linting uses `clippy` via the client scripts.

## Type Safety Rules (Strict)
- `Any` is forbidden in type annotations, including indirect use via `typing.Any`.
- Ignore-based suppression is forbidden (`# type: ignore`, `# pyright: ignore`, `# noqa: ANN`, or similar).
- Use precise types, casts, and guards instead of weakening types or silencing errors.

## Testing Guidelines
- Pytest with asyncio auto mode; test files `test_*.py`, functions `test_*`.
- Use markers: `@pytest.mark.slow` for model-loading tests and `@pytest.mark.integration` for external services.
- Integration tests may require PostgreSQL via `NOTEFLOW_DATABASE_URL`.
- React unit tests use Vitest; e2e uses Playwright from `client/e2e/`.
- Keep proto/type changes covered with at least one backend test and one client-facing test.

## Commit & Pull Request Guidelines
- Use Conventional Commits (e.g., `feat:`, `fix:`, `chore:`) and include a concise scope when helpful.
- PRs should describe the change, link related issues/specs, note DB or proto changes, and include UI screenshots when any client UI changes.

## Configuration & Security Notes
- Runtime settings come from `.env` or `NOTEFLOW_` environment variables (see `src/noteflow/config/settings.py`).
- Keep secrets and local credentials out of the repo; use `.env` and local config instead.
