Update project documentation and configuration files
- Expanded `.gitignore` to include temporary files and scratch documents. - Enhanced `AGENTS.md` with guidelines on using Conventional Commits and PR descriptions. - Added configuration notes to `README.md` for environment variable usage. - Updated `pyproject.toml` to reflect changes in dependencies and comments. - Introduced new files for client configuration and testing, including Prettier settings and Playwright tests. - Removed deprecated client components and adjusted related documentation accordingly. - Added new tests for various components and functionalities to improve coverage.
This commit is contained in:
89
CLAUDE.md
89
CLAUDE.md
@@ -4,7 +4,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Project Overview
|
||||
|
||||
NoteFlow is an intelligent meeting notetaker: local-first audio capture + navigable recall + evidence-linked summaries. Client-server architecture using gRPC for bidirectional audio streaming and transcription.
|
||||
NoteFlow is an intelligent meeting notetaker: local-first audio capture + navigable recall + evidence-linked summaries. It is a client-server system built around a gRPC API for bidirectional audio streaming and transcription. The repository includes:
|
||||
- A Python backend (`src/noteflow/`) hosting the gRPC server, domain logic, and infrastructure adapters.
|
||||
- A Tauri + React desktop client (`client/`) that uses Rust for IPC and a React UI (Vite).
|
||||
|
||||
The gRPC schema is the shared contract between backend and client; keep proto changes in sync across Python, Rust, and TypeScript.
|
||||
|
||||
## Quick Orientation (Start Here)
|
||||
|
||||
- Backend server entry point: `python -m noteflow.grpc.server` (implementation in `src/noteflow/grpc/service.py`).
|
||||
- Tauri/React client: `cd client && npm run dev` (web), `npm run tauri dev` (desktop).
|
||||
- Tauri IPC bridge: TypeScript calls in `client/src/lib/tauri.ts` map to Rust commands in `client/src-tauri/src/commands/`.
|
||||
- Protobuf schema and generated Python stubs live in `src/noteflow/grpc/proto/`.
|
||||
|
||||
## Build and Development Commands
|
||||
|
||||
@@ -15,8 +26,13 @@ python -m pip install -e ".[dev]"
|
||||
# Run gRPC server
|
||||
python -m noteflow.grpc.server --help
|
||||
|
||||
# Run Flet client UI
|
||||
python -m noteflow.client.app --help
|
||||
# Run Tauri + React client UI
|
||||
cd client
|
||||
npm install
|
||||
npm run dev
|
||||
# Desktop Tauri dev (requires Rust toolchain)
|
||||
npm run tauri dev
|
||||
cd -
|
||||
|
||||
# Tests
|
||||
pytest # Full suite
|
||||
@@ -30,6 +46,14 @@ ruff check --fix . # Autofix
|
||||
mypy src/noteflow # Strict type checks
|
||||
basedpyright # Additional type checks
|
||||
|
||||
# Client lint/format (from client/)
|
||||
npm run lint # Biome
|
||||
npm run lint:fix # Biome autofix
|
||||
npm run format # Prettier
|
||||
npm run format:check # Prettier check
|
||||
npm run lint:rs # Clippy (Rust)
|
||||
npm run format:rs # rustfmt (Rust)
|
||||
|
||||
# Docker development
|
||||
docker compose up -d postgres # PostgreSQL with health checks
|
||||
python scripts/dev_watch_server.py # Auto-reload server (watches src/)
|
||||
@@ -68,17 +92,26 @@ src/noteflow/
|
||||
│ ├── export/ # Markdown/HTML export
|
||||
│ └── converters/ # ORM ↔ domain entity converters
|
||||
├── grpc/ # Proto definitions, server, client, meeting store, modular mixins
|
||||
├── client/ # Flet UI app + components (transcript, VU meter, playback, trigger mixin)
|
||||
└── config/ # Pydantic settings (NOTEFLOW_ env vars)
|
||||
```
|
||||
|
||||
Frontend (Tauri + React) lives outside the Python package:
|
||||
|
||||
```
|
||||
client/
|
||||
├── src/ # React UI, state, and view components
|
||||
├── src-tauri/ # Rust/Tauri shell, IPC commands, gRPC client
|
||||
├── e2e/ # Playwright tests
|
||||
├── package.json # Vite + test/lint scripts
|
||||
└── vite.config.ts # Vite configuration
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- Hexagonal architecture: domain → application → infrastructure
|
||||
- Repository pattern with Unit of Work (`SQLAlchemyUnitOfWork`)
|
||||
- gRPC bidirectional streaming for audio → transcript flow
|
||||
- Protocol-based DI (see `domain/ports/` and infrastructure `protocols.py` files)
|
||||
- Modular gRPC mixins for separation of concerns (see below)
|
||||
- `BackgroundWorkerMixin` for standardized thread lifecycle in components
|
||||
|
||||
## gRPC Mixin Architecture
|
||||
|
||||
@@ -98,6 +131,12 @@ grpc/_mixins/
|
||||
|
||||
Each mixin operates on `ServicerHost` protocol, enabling clean composition in `NoteFlowServicer`.
|
||||
|
||||
## Client Architecture (Tauri + React)
|
||||
|
||||
- React components are in `client/src/components/`, shared UI types in `client/src/types/`, and Zustand state in `client/src/store/`.
|
||||
- Tauri IPC calls live in `client/src/lib/tauri.ts` and map to Rust handlers in `client/src-tauri/src/commands/`.
|
||||
- Rust application entry points are `client/src-tauri/src/main.rs` and `client/src-tauri/src/lib.rs`; shared runtime state is in `client/src-tauri/src/state/`.
|
||||
|
||||
## Database
|
||||
|
||||
PostgreSQL with pgvector extension. Async SQLAlchemy with asyncpg driver.
|
||||
@@ -116,6 +155,7 @@ Connection via `NOTEFLOW_DATABASE_URL` env var or settings.
|
||||
- Markers: `@pytest.mark.slow` (model loading), `@pytest.mark.integration` (external services)
|
||||
- Integration tests use testcontainers for PostgreSQL
|
||||
- Asyncio auto-mode enabled
|
||||
- React unit tests use Vitest; e2e tests use Playwright in `client/e2e/`.
|
||||
|
||||
## Proto/gRPC
|
||||
|
||||
@@ -130,17 +170,46 @@ python -m grpc_tools.protoc -I src/noteflow/grpc/proto \
|
||||
src/noteflow/grpc/proto/noteflow.proto
|
||||
```
|
||||
|
||||
**Sync points (high risk of breakage):**
|
||||
- Rust gRPC types are generated at build time by `client/src-tauri/build.rs`. Keep Rust DTOs aligned with proto changes.
|
||||
- Frontend enums/DTOs in `client/src/types/` mirror proto enums and backend domain types; update these when proto enums change.
|
||||
- When adding or renaming RPCs, update: server mixins, `src/noteflow/grpc/client.py`, Tauri command handlers, and `client/src/lib/tauri.ts`.
|
||||
|
||||
## Common Pitfalls & Change Checklist
|
||||
|
||||
### Proto / API evolution
|
||||
- Update the schema in `src/noteflow/grpc/proto/noteflow.proto` first; treat it as the source of truth.
|
||||
- Regenerate Python stubs (`*_pb2.py`, `*_pb2_grpc.py`) and verify imports still align in `src/noteflow/grpc/`.
|
||||
- Ensure the gRPC server mixins in `src/noteflow/grpc/_mixins/` implement new/changed RPCs.
|
||||
- Update `src/noteflow/grpc/client.py` (Python client wrapper) to match the RPC signature and response types.
|
||||
- Update Tauri/Rust command handlers (`client/src-tauri/src/commands/`) and any Rust gRPC types used by commands.
|
||||
- Update TypeScript wrappers in `client/src/lib/tauri.ts` and shared DTOs/enums in `client/src/types/`.
|
||||
- Add/adjust tests on both sides (backend unit/integration + client unit tests) when changing payload shapes.
|
||||
|
||||
### Database schema & migrations
|
||||
- Schema changes belong in `src/noteflow/infrastructure/persistence/` plus an Alembic migration in `src/noteflow/infrastructure/persistence/migrations/`.
|
||||
- Use `alembic revision --autogenerate` only after updating models; review the migration for correctness.
|
||||
- Keep `NOTEFLOW_DATABASE_URL` in mind when running integration tests; default behavior may fall back to memory storage.
|
||||
- Update repository/UnitOfWork implementations if new tables or relations are introduced.
|
||||
- If you add fields used by export/summarization, ensure converters in `infrastructure/converters/` are updated too.
|
||||
|
||||
### Client sync points (Rust + TS)
|
||||
- Tauri IPC surfaces (Rust commands) must match the TypeScript calls in `client/src/lib/tauri.ts`.
|
||||
- Rust gRPC types are generated by `client/src-tauri/build.rs`; verify the proto path if you move proto files.
|
||||
- Frontend enums in `client/src/types/` mirror backend/proto enums; keep them aligned to avoid silent UI bugs.
|
||||
|
||||
## Code Style
|
||||
|
||||
- Python 3.12+, 100-char line length
|
||||
- Strict mypy (allow `type: ignore[code]` only with comment explaining why)
|
||||
- Ruff for linting (E, W, F, I, B, C4, UP, SIM, RUF)
|
||||
- Module soft limit 500 LoC, hard limit 750 LoC
|
||||
- Frontend formatting uses Prettier (single quotes, 100 char width); linting uses Biome.
|
||||
- Rust formatting uses `rustfmt`; linting uses `clippy` via the client scripts.
|
||||
|
||||
## Spikes (De-risking Experiments)
|
||||
|
||||
`spikes/` contains validated platform experiments with `FINDINGS.md`:
|
||||
- `spike_01_ui_tray_hotkeys/` - Flet + pystray + pynput (requires X11)
|
||||
- `spike_02_audio_capture/` - sounddevice + PortAudio
|
||||
- `spike_03_asr_latency/` - faster-whisper benchmarks (0.05x real-time)
|
||||
- `spike_04_encryption/` - keyring + AES-GCM (826 MB/s throughput)
|
||||
@@ -227,14 +296,6 @@ python -m grpc_tools.protoc -I src/noteflow/grpc/proto \
|
||||
|----------|---------|
|
||||
| `parse_calendar_events()` | Parse events from config/env |
|
||||
|
||||
### Client Mixins (`client/components/`)
|
||||
|
||||
| Class | Purpose |
|
||||
|-------|---------|
|
||||
| `BackgroundWorkerMixin` | Thread lifecycle: `_start_worker()`, `_stop_worker()`, `_should_run()` |
|
||||
| `AsyncOperationMixin[T]` | Async ops with state: `run_async_operation()` |
|
||||
| `TriggerMixin` | Trigger signal polling |
|
||||
|
||||
### Recovery Service (`application/services/recovery_service.py`)
|
||||
|
||||
| Method | Purpose |
|
||||
|
||||
Reference in New Issue
Block a user