nontara/AGENTS.md

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:

  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