noteflow/AGENTS.md

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.