# Database Schema Naming Rules

## Schema Organization
- Schemas must be modular and separated per entity/domain
- Each main entity should have its own schema file (e.g., `movies.ts`, `series.ts`, `people.ts`)

## Junction Table Rules
- Junction tables must be placed in the same file as the related main entity
- Naming convention: `{mainEntity}{RelatedEntity}` in camelCase
- Examples:
  - Movie related to Genres → `movieGenres` (in `movies.ts`)
  - Series related to People → `seriesPeople` (in `series.ts`)
  - Movie related to Credits → `movieCredits` (in `movies.ts`)

## Server Directory Rules (`@apps/server/`)

### Type Definitions - STRICTLY FORBIDDEN
- **NO TypeScript interfaces or types allowed** in `@apps/server/`
- Instead, ALL type definitions must be created as schemas in `@apps/server/src/models/`
- This ensures runtime validation and type safety through schema validation

### Schema Validation Requirements
- **MUST use Zod** for all schema validation
- All models must be defined using Zod schemas
- **Schema names MUST use PascalCase** (e.g., `MovieSchema`, `SeriesSchema`)
- **MUST use Zod v4 syntax** (NOT v3 legacy)
  - ✅ Correct (v4): `z.url()`, `z.email()`, `z.uuid()`
  - ❌ Wrong (v3): `z.string().url()`, `z.string().email()`, `z.string().uuid()`
- **Literal/Constant Values MUST use UPPERCASE**
  - All literal string values in union types must be UPPERCASE
  - This applies to TypeScript types, Zod schemas, and enums
  - ✅ Correct: `export type ProviderType = "MOVIE" | "SERIES" | "PERSON";`
  - ✅ Correct: `z.enum(["MOVIE", "SERIES", "PERSON"])`
  - ❌ Wrong: `export type ProviderType = "movie" | "series" | "person";`
- Export both the schema and the inferred type from each model file
- Example pattern:
  ```typescript
  import { z } from 'zod';

  export const MovieSchema = z.object({
    id: z.uuid(),
    title: z.string(),
    imdbUrl: z.url().optional(),
    // other fields...
  });

  export type Movie = z.infer<typeof MovieSchema>;
  ```

### Models Organization
- Models must be modular and separated per domain/entity
- Each model should have its own file in `@apps/server/src/models/`
- Examples:
  - `@apps/server/src/models/movie.ts`
  - `@apps/server/src/models/series.ts`
  - `@apps/server/src/models/people.ts`

## Code Quality and Linting

### IDE Diagnostics - REQUIRED FIRST STEP
- **MUST check IDE diagnostics BEFORE running the linter**
- Use `getIdeDiagnostics` tool to check for TypeScript errors and warnings
- Resolve ALL diagnostic problems (type errors, unused imports, etc.) first
- Only after fixing IDE diagnostics should you proceed to run the linter
- This prevents linting cosmetic issues while type errors remain unfixed

### Type Checking - REQUIRED FOR apps/server FILES
- **For files inside `apps/server/` folder:**
  - **MUST run type checking BEFORE running the biome linter**
  - Use command: `bun run check-types`
  - Fix ALL type errors before proceeding to the biome linter
  - This ensures type safety is verified before code formatting

### Biome Linter - MANDATORY
- **MUST run Biome linter after creating or editing any file**
- **ONLY run linter on files that YOU (the AI agent) have modified**
  - Do NOT run linter on the entire project (`bun run check`)
  - ALWAYS use file-specific linting: `bunx biome check --write <file-path>`
  - Only lint files that were created or edited in the current task
- The linter will:
  - Format code according to project style
  - Fix auto-fixable issues
  - Report remaining issues that need manual fixes
- **Do NOT skip linting** - it ensures code consistency across the project
- If linter reports errors, fix them before considering the task complete