# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Tusk is a PostgreSQL database management GUI built with Tauri 2 (Rust backend) and React (TypeScript frontend).

## Development Commands

```bash
npm run tauri dev     # Start full app in dev mode (Vite HMR + Rust backend)
npm run dev           # Start only the Vite frontend dev server (port 5173)
npm run build         # Build frontend (tsc + vite build)
npm run tauri build   # Build production desktop executable
npm run lint          # ESLint
```

Rust backend builds automatically via Tauri when running `npm run tauri dev/build`. To check Rust compilation independently:
```bash
cd src-tauri && cargo check
```

## Architecture

```
Frontend (React/TS) ──IPC invoke()──> Backend (Rust/Tauri) ──sqlx──> PostgreSQL
```

### IPC Communication Pattern

All frontend-backend communication goes through Tauri's typed IPC. The full pipeline for adding a new backend-exposed feature:

1. **Rust command** — `#[tauri::command]` async fn in `src-tauri/src/commands/<domain>.rs`
2. **Register** — add to `invoke_handler` in `src-tauri/src/lib.rs`
3. **TS wrapper** — typed `invoke()` call in `src/lib/tauri.ts`
4. **React hook** — TanStack React Query hook in `src/hooks/use-<domain>.ts`
5. **Types** — shared interfaces in `src/types/index.ts`

### Backend (src-tauri/src/)

- **`state.rs`** — `AppState`: holds `RwLock<HashMap<connection_id, PgPool>>`, read-only flags, config path. Connections default to read-only.
- **`error.rs`** — `TuskError` enum with `thiserror`, serialized as string for IPC. `TuskResult<T>` type alias.
- **`utils.rs`** — `escape_ident()` for safe SQL identifier quoting.
- **`commands/`** — one module per domain (connections, queries, schema, data, export, management, history, saved_queries). Each function takes `State<'_, AppState>` and returns `TuskResult<T>`.
- **`models/`** — serde-serializable structs matching TypeScript types.

SQL safety: identifiers use `escape_ident()`, data queries use sqlx parameterized queries. Read-only mode wraps queries in `SET TRANSACTION READ ONLY` + `ROLLBACK`.

### Frontend (src/)

- **State**: Zustand store (`stores/app-store.ts`) — connections, active connection/database, tabs, read-only flags, pg version.
- **Data fetching**: TanStack React Query hooks in `hooks/` — one hook per domain, wrapping `src/lib/tauri.ts` functions.
- **UI**: shadcn/ui + Radix primitives, Tailwind CSS 4, dark mode via next-themes. SQL editor uses CodeMirror.
- **Layout**: resizable panels (sidebar + main area with tab bar).

### Stored Data

Connections are persisted to `~/.config/tusk/connections.json`. History and saved queries are stored in similar JSON files in the same config directory.

## Conventions

- **Frontend files**: Components `PascalCase.tsx`, hooks `use-kebab-case.ts`, one feature per directory under `components/`
- **Path alias**: `@` maps to `./src`
- **Rust errors**: always use `TuskError` variants, never `unwrap()` in commands
- **New PG types**: add conversion case in `pg_value_to_json()` in `commands/queries.rs`