From 46274ff22219a20020bded07d7aa6a2ddcd65ed1 Mon Sep 17 00:00:00 2001
From: Travis Vasceannie <travis.vas@gmail.com>
Date: Tue, 20 Jan 2026 03:51:36 +0000
Subject: [PATCH] docs: add style and quality guidelines

---
 .claude/rules/STYLE_QUALITY_GUIDELINES.md | 89 +++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 .claude/rules/STYLE_QUALITY_GUIDELINES.md

diff --git a/.claude/rules/STYLE_QUALITY_GUIDELINES.md b/.claude/rules/STYLE_QUALITY_GUIDELINES.md
new file mode 100644
index 0000000..8615315
--- /dev/null
+++ b/.claude/rules/STYLE_QUALITY_GUIDELINES.md
@@ -0,0 +1,89 @@
+# Style and Quality Guidelines
+
+This document outlines the coding standards, patterns, and architectural decisions for the NoteFlow project. Adherence to these guidelines ensures consistency, maintainability, and quality across the codebase.
+
+## 1. General Principles
+
+*   **Strict Typing:** Both Python and TypeScript codebases enforce strict typing. No implicit `Any` is allowed.
+*   **Async First:** The system is designed with asynchrony at its core (asyncio in Python, Promises/async-await in TypeScript).
+*   **Domain-Driven Design (DDD):** The backend follows DDD principles with clear separation of Domain, Application, and Infrastructure layers.
+*   **Local-First:** The architecture supports local-first operations, with Tauri integration for desktop capabilities.
+*   **Structured Logging:** All logging must be structured and contextual.
+*   **Linter Compliance:** Zero tolerance for linter warnings or errors. CI/CD will fail on violations.
+
+## 2. Python Backend (`src/noteflow`)
+
+### 2.1 Tooling & Environment
+*   **Package Manager:** `uv` is mandated for dependency management.
+*   **Linting/Formatting:** `ruff` is used for both. Line length is **100**.
+*   **Type Checking:** `mypy` and `basedpyright` in **strict mode**.
+    *   Configuration: `strict = true` in `pyproject.toml`.
+    *   Prohibited: `type: ignore` without specific error code and justification.
+*   **Testing:** `pytest` with `pytest-asyncio`.
+
+### 2.2 Architectural Patterns
+*   **Layered Architecture:**
+    *   `domain/`: Pure python logic. No external dependencies (except widely used utils like `uuid`, `datetime`).
+        *   **Entities:** defined as `@dataclass(frozen=True)` or standard classes.
+        *   **Ports:** defined as `typing.Protocol` in `domain/ports`.
+    *   `application/`: Orchestration logic.
+        *   **Services:** Implement use cases.
+        *   **Mixins:** Large services (e.g., `MeetingService`) are composed of Mixins (e.g., `MeetingServiceCrudMixin`) to separate concerns.
+        *   **UnitOfWork:** Used for transaction management.
+    *   `infrastructure/`: Adapters for ports (DB, API, File System).
+*   **Dependency Injection:** Services receive dependencies (repositories, uow) via `__init__`.
+
+### 2.3 Coding Style
+*   **Imports:** Use `from __future__ import annotations`.
+*   **Typing:**
+    *   Use modern union syntax: `str | None` instead of `Optional[str]`.
+    *   Use `list[T]`, `dict[K, V]` built-in generics.
+    *   Use `TYPE_CHECKING` block for circular type hints.
+*   **Async:** All I/O bound operations must be `async`.
+*   **Error Handling:** Use custom exceptions defined in `domain/errors.py` or specific modules.
+*   **Value Objects:** Use strictly for immutable domain concepts (`MeetingId`, `MeetingState`).
+
+## 3. TypeScript Frontend (`client/src`)
+
+### 3.1 Tooling
+*   **Build:** `vite`.
+*   **Linting/Formatting:** `biome` is the primary tool. `eslint` is used for specific type-safety rules.
+*   **Style:** Indentation: 2 spaces. Quotes: Single (JS/TS), Double (JSX).
+
+### 3.2 Architectural Patterns
+*   **Component Structure:**
+    *   `components/ui/`: Generic, reusable components (mostly Shadcn UI style).
+    *   `components/features/`: Domain-specific components (e.g., `recording`, `analytics`).
+    *   `pages/`: Route-level components.
+*   **State Management:**
+    *   **Local State:** `useState` for simple component state.
+    *   **Complex Logic:** Encapsulate in custom hooks (e.g., `useRecordingSession`).
+    *   **Global/Shared:** React Context (e.g., `ConnectionStateContext`).
+*   **API Layer:**
+    *   All API calls go through `src/api`.
+    *   `getAPI()` factory allows switching between real and mock implementations.
+    *   Types are strictly defined in `src/api/types`.
+
+### 3.3 Coding Style
+*   **Components:** Functional components using `export function ComponentName`.
+*   **Props:** Define explicitly as `interface ComponentProps`.
+*   **Styling:** Tailwind CSS.
+    *   Use `cn(...)` utility for class merging.
+    *   Use `cva` for component variants.
+*   **Naming:**
+    *   Files: `kebab-case.ts/tsx`.
+    *   Components: `PascalCase`.
+    *   Hooks: `useCamelCase`.
+*   **Null Safety:**
+    *   Strict null checks are on.
+    *   Avoid non-null assertions (`!`) unless absolutely certain.
+*   **Observability:**
+    *   Use `toast` for user notifications.
+    *   Use `addClientLog` for structural logging.
+
+## 4. Git & Workflow
+
+*   **Commits:** Clear, imperative messages (e.g., "Add meeting service", "Fix race condition in recorder").
+*   **File Organization:**
+    *   Colocation: Tests often mirror the source structure or are located near the code (frontend).
+    *   Modularity: Break down large files. If a file grows too large, consider extracting logic (like the Mixin pattern in services).