Add CLAUDE.md with project conventions and quick reference

https://claude.ai/code/session_013M6WrK2CDSC3JJLnnhio6e

1 files changed, 89 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5f3f3f5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,89 @@
+# Kioku
+
+Spaced repetition learning app (Anki clone). Full-stack TypeScript with Hono backend, React frontend, PostgreSQL database, and offline-first PWA support.
+
+## Quick Reference
+
+```bash
+pnpm install              # Install dependencies
+pnpm dev                  # Start backend server (hot reload)
+pnpm dev:client           # Start frontend dev server (port 5173)
+pnpm build                # Build both server and client
+pnpm test                 # Run tests (Vitest)
+pnpm typecheck            # TypeScript type checking
+pnpm lint                 # Lint with Biome
+pnpm lint:fix             # Auto-fix lint issues
+pnpm format               # Format with Biome
+pnpm db:generate          # Generate database migrations
+pnpm db:migrate           # Run database migrations
+pnpm db:push              # Push schema changes to DB
+```
+
+## Architecture
+
+- **Backend**: Hono on Node.js 22 (built with esbuild) — `src/server/`
+- **Frontend**: React 19 + Vite — `src/client/`
+- **Shared**: Common utilities — `src/shared/`
+- **Database**: PostgreSQL with Drizzle ORM — schema in `src/server/db/`
+- **Migrations**: SQL files in `drizzle/`
+
+### Backend Structure (`src/server/`)
+
+Repository pattern with dependency injection. Routes → Services → Repositories → Drizzle ORM.
+
+- `routes/` — API endpoint handlers
+- `repositories/` — Data access layer
+- `middleware/` — Auth, CORS, error handling, rate limiting
+- `schemas/` — Zod validation schemas
+- `services/` — Business logic
+- `types/` — TypeScript interfaces (includes repository interfaces)
+- `db/schema.ts` — Drizzle database schema
+
+### Frontend Structure (`src/client/`)
+
+- `pages/` — Route-level page components
+- `components/` — Reusable React components
+- `atoms/` — Jotai state management atoms
+- `api/` — API client
+- `db/` — Dexie.js IndexedDB schema (offline storage)
+- `sync/` — Sync engine (client ↔ server)
+- `utils/` — Utilities (CSV parser, template renderer)
+
+### Key Libraries
+
+- **State**: Jotai (atoms suffixed with `Atom`)
+- **Routing**: Wouter
+- **Styling**: Tailwind CSS v4
+- **Sync**: Automerge CRDT for conflict-free offline sync
+- **Scheduling**: ts-fsrs (spaced repetition algorithm)
+- **Validation**: Zod
+
+## Code Style
+
+- **Formatter/Linter**: Biome (run `pnpm lint` to check, `pnpm lint:fix` to auto-fix)
+- **Indentation**: Tabs
+- **Quotes**: Double quotes for JS/TS
+- **Imports**: Organized by Biome (auto-sorted)
+- **Naming**: PascalCase for components/types, camelCase for functions/variables, atoms suffixed with `Atom`
+- **Tests**: Co-located with source files (`*.test.ts`, `*.test.tsx`)
+
+## Database Conventions
+
+- Soft deletes via `deletedAt` timestamp
+- Sync versioning via `syncVersion` field
+- All tables have `createdAt` and `updatedAt` timestamps with timezone
+
+## Testing
+
+Vitest with `@testing-library/react` for component tests. Tests run with:
+
+```bash
+pnpm test           # Single run
+pnpm test:watch     # Watch mode
+```
+
+Test environment uses `JWT_SECRET=test-secret-key` and mock factories for test data. IndexedDB is mocked with `fake-indexeddb`.
+
+## CI Pipeline
+
+Lint → Typecheck → Test → Build (see `.github/workflows/ci.yaml`)