108 lines
4.5 KiB
Markdown
108 lines
4.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build & Run Commands
|
|
|
|
```sh
|
|
pnpm install # install deps
|
|
pnpm dev # start all apps in dev mode (API :4000, Web :3000)
|
|
pnpm build # prod build all packages
|
|
pnpm lint # ESLint across all packages
|
|
pnpm typecheck # strict TypeScript checks
|
|
pnpm test # run all Vitest tests
|
|
pnpm format # Prettier format
|
|
pnpm clean # remove dist + .turbo + node_modules
|
|
```
|
|
|
|
Single package:
|
|
```sh
|
|
pnpm --filter @yetanother/web dev
|
|
pnpm --filter @yetanother/api dev
|
|
pnpm --filter @yetanother/api exec prisma studio
|
|
pnpm --filter @yetanother/web test:watch
|
|
pnpm --filter @yetanother/web test:e2e # Playwright
|
|
pnpm --filter @yetanother/web test -- -t "test name"
|
|
```
|
|
|
|
Database:
|
|
```sh
|
|
pnpm --filter @yetanother/db db:migrate # create migration
|
|
pnpm --filter @yetanother/db db:deploy # apply migrations (prod)
|
|
pnpm --filter @yetanother/db db:seed # seed dev data
|
|
pnpm --filter @yetanother/db exec prisma generate # regen Prisma client
|
|
```
|
|
|
|
Desktop (Tauri v2, requires Rust):
|
|
```sh
|
|
cd apps/desktop && pnpm tauri dev
|
|
cd apps/desktop && pnpm tauri build
|
|
```
|
|
|
|
Infra:
|
|
```sh
|
|
docker compose up -d postgres redis meilisearch
|
|
docker compose up --build # full prod build
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
- **Monorepo**: Turborepo + pnpm workspaces (pnpm 11+)
|
|
- **Frontend**: React 19 + TypeScript strict, Vite 6, Tailwind CSS 4, shadcn/ui-style (Radix primitives)
|
|
- **State**: Zustand (global stores), TanStack React Query (server), Jotai (local UI), react-router-dom v7
|
|
- **Editor**: TipTap / ProseMirror (block-based with tables, task lists, code blocks, slash menu)
|
|
- **Backend**: Fastify 5, Prisma ORM + PostgreSQL 16 (pgvector), Redis (ioredis), Zod validation
|
|
- **Real-time**: Yjs (CRDT) + WebSocket (fastify-websocket), y-prosemirror, y-indexeddb
|
|
- **Search**: Meilisearch (full-text) + pgvector (semantic embeddings)
|
|
- **API**: REST (under `/api/v1/`) + GraphQL (Mercurius at `/graphql`)
|
|
- **Desktop**: Tauri v2 (Rust)
|
|
- **Testing**: Vitest + React Testing Library + jsdom, Playwright (E2E)
|
|
- **i18n**: i18next + react-i18next
|
|
- **Auth**: JWT (fastify-jwt) with refresh tokens, bcryptjs
|
|
|
|
## Architecture
|
|
|
|
### Monorepo layout
|
|
```
|
|
apps/
|
|
api/ — Fastify server (REST + GraphQL + WebSocket)
|
|
web/ — React SPA (Vite, Tailwind, TipTap editor)
|
|
desktop/ — Tauri wrapper around web app
|
|
mobile/ — React Native (not started)
|
|
packages/
|
|
db/ — Prisma schema + client, seed data
|
|
types/ — Zod schemas + TypeScript types (shared frontend/backend)
|
|
ui/ — Radix-based component library (button, dialog, tabs, toast, tooltip)
|
|
hooks/ — Shared React hooks (useDebounce, useLocalStorage, useMediaQuery)
|
|
utils/ — Shared utilities (cn, constants)
|
|
tooling/
|
|
eslint/ — Shared ESLint configs (base, node, react)
|
|
typescript/ — Shared TS configs (base, node, react)
|
|
```
|
|
|
|
### Data model (Node-based)
|
|
Everything is a **Node** — tasks, events, notes, projects, goals share a unified schema. Nodes have polymorphic types, parent/child hierarchies, typed links (references, blocks, relates_to, etc.), tags, and version-based optimistic concurrency. Embeddings store pgvector vectors for semantic search.
|
|
|
|
### API patterns
|
|
- Routes registered in `apps/api/src/main.ts` under `/api/v1` prefix
|
|
- Auth via JWT with refresh token rotation (cookie + bearer)
|
|
- Route handlers: `app.get('/nodes', async (request) => { ... })` with `app.prisma` decorator
|
|
- Zod body validation inline in route files
|
|
- Background: Meilisearch indexing + activity logging fire-and-forget (.catch(() => {}))
|
|
- Error handling: `AppError` class + `handleError` helper (Zod errors → 400, AppError → statusCode, else → 500)
|
|
|
|
### Frontend patterns
|
|
- Zustand stores for UI state (stores/notes.ts, stores/tasks.ts, stores/calendar.ts)
|
|
- API client in `lib/api.ts` with auto-refresh on 401
|
|
- TipTap editor with custom extensions, toolbar, slash menu
|
|
- React.lazy route splitting for notes/tasks/calendar pages
|
|
- Calendar: drag-and-drop events, multi-view (day/week/month), event dialog
|
|
- Tasks: drag-and-drop reorder (dnd-kit), views (list/board/timeline), NL date parsing (chrono-node)
|
|
|
|
### Key constraints
|
|
- All objects belong to a workspace (multi-tenant via workspaceId)
|
|
- Soft delete via `status: 'deleted'` on nodes
|
|
- Optimistic concurrency on node updates via `version` field
|
|
- Pre-commit: Husky runs lint-staged (ESLint + Prettier)
|
|
- Commit style: conventional commits (`feat:`, `fix:`, `refactor:`, etc.)
|