|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Build System |
| 8 | +- `pnpm build` - Build all packages using Turbo |
| 9 | +- `pnpm watch` - Watch mode for all packages |
| 10 | +- `pnpm lint` - Run ESLint across all packages |
| 11 | +- `pnpm test` - Run tests for all packages |
| 12 | + |
| 13 | +### Package Management |
| 14 | +- Uses `pnpm` with workspaces |
| 15 | +- Package manager is pinned to `[email protected]` |
| 16 | +- Packages are located in `packages/`, `samples/`, and `tests/` |
| 17 | + |
| 18 | +### Testing |
| 19 | +- Runtime package tests: `pnpm test` (includes vitest, typing generation, and typecheck) |
| 20 | +- CLI tests: `pnpm test` |
| 21 | +- E2E tests are in `tests/e2e/` directory |
| 22 | + |
| 23 | +### ZenStack CLI Commands |
| 24 | +- `npx zenstack init` - Initialize ZenStack in a project |
| 25 | +- `npx zenstack generate` - Compile ZModel schema to TypeScript |
| 26 | +- `npx zenstack db push` - Sync schema to database (uses Prisma) |
| 27 | +- `npx zenstack migrate dev` - Create and apply migrations |
| 28 | +- `npx zenstack migrate deploy` - Deploy migrations to production |
| 29 | + |
| 30 | +## Architecture Overview |
| 31 | + |
| 32 | +### Core Components |
| 33 | +- **@zenstackhq/runtime** - Main database client and ORM engine built on Kysely |
| 34 | +- **@zenstackhq/cli** - Command line interface and project management |
| 35 | +- **@zenstackhq/language** - ZModel language specification and parser (uses Langium) |
| 36 | +- **@zenstackhq/sdk** - Code generation utilities and schema processing |
| 37 | + |
| 38 | +### Key Architecture Patterns |
| 39 | +- **Monorepo Structure**: Uses pnpm workspaces with Turbo for build orchestration |
| 40 | +- **Language-First Design**: ZModel DSL compiles to TypeScript, not runtime code generation |
| 41 | +- **Kysely-Based ORM**: V3 uses Kysely as query builder instead of Prisma runtime dependency |
| 42 | +- **Plugin Architecture**: Runtime plugins for query interception and entity mutation hooks |
| 43 | + |
| 44 | +### ZModel to TypeScript Flow |
| 45 | +1. ZModel schema (`schema.zmodel`) defines database structure and policies |
| 46 | +2. `zenstack generate` compiles ZModel to TypeScript schema (`schema.ts`) |
| 47 | +3. Schema is used to instantiate `ZenStackClient` with type-safe CRUD operations |
| 48 | +4. Client provides both high-level ORM API and low-level Kysely query builder |
| 49 | + |
| 50 | +### Package Dependencies |
| 51 | +- **Runtime**: Depends on Kysely, Zod, and various utility libraries |
| 52 | +- **CLI**: Depends on language package, Commander.js, and Prisma (for migrations) |
| 53 | +- **Language**: Uses Langium for grammar parsing and AST generation |
| 54 | +- **Database Support**: SQLite (better-sqlite3) and PostgreSQL (pg) only |
| 55 | + |
| 56 | +### Testing Strategy |
| 57 | +- Runtime package has comprehensive client API tests and policy tests |
| 58 | +- CLI has action-specific tests for commands |
| 59 | +- E2E tests validate real-world schema compatibility (cal.com, formbricks, trigger.dev) |
| 60 | +- Type coverage tests ensure TypeScript inference works correctly |
| 61 | + |
| 62 | +## Key Differences from Prisma |
| 63 | +- No runtime dependency on @prisma/client |
| 64 | +- Pure TypeScript implementation without Rust/WASM |
| 65 | +- Built-in access control and validation (coming soon) |
| 66 | +- Kysely query builder as escape hatch instead of raw SQL |
| 67 | +- Schema-first approach with ZModel DSL extension of Prisma schema language |
| 68 | + |
| 69 | +## Development Notes |
| 70 | +- Always run `zenstack generate` after modifying ZModel schemas |
| 71 | +- Database migrations still use Prisma CLI under the hood |
| 72 | +- Plugin system allows interception at ORM, Kysely, and entity mutation levels |
| 73 | +- Computed fields are evaluated at database level for performance |
0 commit comments