|
| 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 | +### Package Management |
| 8 | +**Important**: Use pnpm for package management. |
| 9 | +- `pnpm install` - Install dependencies |
| 10 | +- `pnpm add <package>` - Add new dependency |
| 11 | +- `pnpm remove <package>` - Remove dependency |
| 12 | + |
| 13 | +### Build and Run |
| 14 | +- `pnpm dev` - Start development server with hot reload ⚠️ **DO NOT USE** - Never run dev mode during development |
| 15 | +- `pnpm start` - Run the application in production mode |
| 16 | +- `pnpm build` - Build the project for production (outputs to ./dist) |
| 17 | + |
| 18 | +**IMPORTANT**: Never run `pnpm dev` during development work. The development server should only be started by the user manually when they want to test the application. Use tests instead of running the dev server. |
| 19 | + |
| 20 | +### Code Quality |
| 21 | +- `pnpm typecheck` - Run TypeScript type checking without emitting files |
| 22 | +- `pnpm lint` - Run Biome on all TypeScript/JavaScript files |
| 23 | +- `pnpm lint:fix` - Run Biome with automatic fixes on all files |
| 24 | + |
| 25 | +### Testing |
| 26 | +- `pnpm test` - Run all tests once |
| 27 | +- `pnpm test:watch` - Run tests in watch mode |
| 28 | +- Uses Vitest with @effect/vitest for Effect-aware testing |
| 29 | +- Test files: `test/**/*.test.ts` and `src/**/*.test.ts` |
| 30 | + |
| 31 | +### Database |
| 32 | +- `pnpm prisma generate` - Generate Prisma client |
| 33 | +- `pnpm prisma migrate dev` - Run database migrations in development |
| 34 | +- `pnpm prisma studio` - Open Prisma Studio GUI |
| 35 | + |
| 36 | +**CRITICAL DEVELOPMENT RULE**: After EVERY file change, you MUST: |
| 37 | +1. Run `pnpm lint:fix` immediately |
| 38 | +2. Run `pnpm typecheck` immediately |
| 39 | +3. Fix ALL lint errors and type errors before proceeding |
| 40 | +4. Do NOT continue development until both commands pass without errors |
| 41 | + |
| 42 | +This is non-negotiable and applies to every single file modification. |
| 43 | + |
| 44 | +## Project Architecture |
| 45 | + |
| 46 | +### Technology Stack |
| 47 | +- **Runtime**: Node.js with tsx for development |
| 48 | +- **Language**: TypeScript with ES2022 target |
| 49 | +- **Framework**: Effect Platform HTTP API |
| 50 | +- **Database**: SQLite with Prisma ORM |
| 51 | +- **Authentication**: Privy for external auth, custom session tokens for internal |
| 52 | + |
| 53 | +### Code Style |
| 54 | +- Uses Biome for linting and formatting (monorepo configuration) |
| 55 | +- Line width: 120 characters, 2-space indentation |
| 56 | +- Single quotes for JavaScript/TypeScript |
| 57 | + |
| 58 | +### TypeScript Configuration |
| 59 | +- Strict mode enabled |
| 60 | +- Effect patterns preferred (Effect.fn over Effect.gen) |
| 61 | +- No emit configuration (build handled by tsup) |
| 62 | +- Path aliases configured: `server-new/*` maps to `./src/*` |
| 63 | + |
| 64 | +### Project Structure |
| 65 | +- `src/` - Source code directory |
| 66 | + - `config/` - Configuration modules |
| 67 | + - `http/` - HTTP API definitions and handlers |
| 68 | + - `services/` - Business logic services |
| 69 | + - `domain/` - Domain models (Effect Schema) |
| 70 | +- `prisma/` - Database schema and migrations |
| 71 | +- `test/` - Test files |
| 72 | +- `specs/` - Feature specifications |
| 73 | +- `patterns/` - Implementation patterns documentation |
| 74 | + |
| 75 | +## Development Workflow - Spec-Driven Development |
| 76 | + |
| 77 | +This project follows a **spec-driven development** approach where every feature is thoroughly specified before implementation. |
| 78 | + |
| 79 | +**CRITICAL RULE: NEVER IMPLEMENT WITHOUT FOLLOWING THE COMPLETE SPEC FLOW** |
| 80 | + |
| 81 | +### Mandatory Workflow Steps |
| 82 | + |
| 83 | +**AUTHORIZATION PROTOCOL**: Before proceeding to any phase (2-5), you MUST: |
| 84 | +1. Present the completed work from the current phase |
| 85 | +2. Explicitly ask for user authorization to proceed |
| 86 | +3. Wait for clear user approval before continuing |
| 87 | +4. NEVER assume permission or proceed automatically |
| 88 | + |
| 89 | +### Phase-by-Phase Process |
| 90 | + |
| 91 | +**Phase 1**: Create `instructions.md` (initial requirements capture) |
| 92 | +- Create feature folder and capture user requirements |
| 93 | +- Document user stories, acceptance criteria, constraints |
| 94 | + |
| 95 | +**Phase 2**: Derive `requirements.md` from instructions - **REQUIRES USER APPROVAL** |
| 96 | +- Structured analysis of functional/non-functional requirements |
| 97 | +- STOP and ask for authorization before proceeding to Phase 3 |
| 98 | + |
| 99 | +**Phase 3**: Create `design.md` from requirements - **REQUIRES USER APPROVAL** |
| 100 | +- Technical design and implementation strategy |
| 101 | +- STOP and ask for authorization before proceeding to Phase 4 |
| 102 | + |
| 103 | +**Phase 4**: Generate `plan.md` from design - **REQUIRES USER APPROVAL** |
| 104 | +- Implementation roadmap and task breakdown |
| 105 | +- STOP and ask for authorization before proceeding to Phase 5 |
| 106 | + |
| 107 | +**Phase 5**: Execute implementation - **REQUIRES USER APPROVAL** |
| 108 | +- Follow the plan exactly as specified |
| 109 | +- NEVER start implementation without explicit user approval |
| 110 | + |
| 111 | +## Effect TypeScript Development Patterns |
| 112 | + |
| 113 | +### Core Principles |
| 114 | +- **Type Safety First**: Never use `any` or type assertions - prefer explicit types |
| 115 | +- **Effect Patterns**: Use Effect's composable abstractions (prefer Effect.fn) |
| 116 | +- **Early Returns**: Prefer early returns over deep nesting |
| 117 | +- **Input Validation**: Validate inputs at system boundaries with Effect Schema |
| 118 | +- **Resource Safety**: Use Effect's resource management for automatic cleanup |
| 119 | + |
| 120 | +### Effect-Specific Patterns |
| 121 | + |
| 122 | +#### Sequential Operations (Effect.fn preferred) |
| 123 | +```typescript |
| 124 | +// Use Effect.fn for sequential operations |
| 125 | +const program = Effect.fn(function* () { |
| 126 | + const user = yield* getUser(id) |
| 127 | + const profile = yield* getProfile(user.profileId) |
| 128 | + return { user, profile } |
| 129 | +}) |
| 130 | +``` |
| 131 | + |
| 132 | +#### Error Handling |
| 133 | +```typescript |
| 134 | +// Use Data.TaggedError for custom errors |
| 135 | +class UserNotFound extends Data.TaggedError("UserNotFound")<{ |
| 136 | + readonly id: string |
| 137 | +}> {} |
| 138 | + |
| 139 | +// Use Effect.tryPromise for Promise integration |
| 140 | +const fetchUser = (id: string) => |
| 141 | + Effect.tryPromise({ |
| 142 | + try: () => prisma.user.findUniqueOrThrow({ where: { id } }), |
| 143 | + catch: () => new UserNotFound({ id }) |
| 144 | + }) |
| 145 | +``` |
| 146 | + |
| 147 | +#### Testing with @effect/vitest |
| 148 | + |
| 149 | +**Use @effect/vitest for Effect code:** |
| 150 | +- Import pattern: `import { assert, describe, it } from "@effect/vitest"` |
| 151 | +- Test pattern: `it.effect("description", () => Effect.fn(function*() { ... }))` |
| 152 | +- **FORBIDDEN**: Never use `expect` from vitest in Effect tests - use `assert` methods |
| 153 | + |
| 154 | +#### Correct it.effect Pattern |
| 155 | + |
| 156 | +```typescript |
| 157 | +import { assert, describe, it } from "@effect/vitest" |
| 158 | +import { Effect } from "effect" |
| 159 | + |
| 160 | +describe("UserService", () => { |
| 161 | + it.effect("should fetch user successfully", () => |
| 162 | + Effect.fn(function* () { |
| 163 | + const user = yield* fetchUser("123") |
| 164 | + |
| 165 | + // Use assert methods, NOT expect |
| 166 | + assert.strictEqual(user.id, "123") |
| 167 | + assert.deepStrictEqual(user.profile, expectedProfile) |
| 168 | + assert.isTrue(user.active) |
| 169 | + })) |
| 170 | +}) |
| 171 | +``` |
| 172 | + |
| 173 | +## Implementation Patterns |
| 174 | + |
| 175 | +The project includes comprehensive pattern documentation for future reference and consistency: |
| 176 | + |
| 177 | +### Pattern Directory |
| 178 | +**Location**: `patterns/` |
| 179 | +- **Purpose**: Detailed documentation of all implementation patterns used in the project |
| 180 | +- **Usage**: Reference material for maintaining consistency and best practices |
| 181 | + |
| 182 | +### Available Patterns |
| 183 | +- **http-api.md**: HTTP API definition and implementation patterns |
| 184 | +- **layer-composition.md**: Layer-based dependency injection patterns |
| 185 | +- **generic-testing.md**: General testing patterns with @effect/vitest |
| 186 | + |
| 187 | +## Notes |
| 188 | +- This is an Effect Platform HTTP API migration of the original Express server |
| 189 | +- Focus on type safety, observability, and error handling |
| 190 | +- WebSocket functionality excluded (to be migrated separately) |
| 191 | +- Uses hardcoded port configuration (no portfinder) |
0 commit comments