Taskhub Api Conventions

Module Structure

Each feature follows the same pattern:

• *.module.ts — imports and exports, declares providers.
• *.resolver.ts — GraphQL queries and mutations; delegates to service.
• *.service.ts — business logic, database access via PrismaService.
• dto/ — input types decorated with @InputType() and class-validator decorators.

Rules:

• Keep resolvers thin; business logic lives in services.
• Never access PrismaClient directly in resolvers; always go through PrismaService.
• One resolver file per feature; split into multiple if it grows past ~200 lines.
• Export only what other modules need; keep internal providers unexported.

GraphQL Conventions (Code-First)

• Use @ObjectType(), @Field(), @InputType(), @Args(), @Query(), @Mutation() decorators.
• schema.gql is auto-generated by NestJS on startup — never edit it by hand.
• Keep resolver method names consistent with the schema operation names.
• Use @UseGuards(JwtAuthGuard) on any query or mutation requiring authentication.
• Use @CurrentUser() decorator to access the authenticated user in resolver methods.
• Validate all inputs with class-validator decorators on DTO classes.
• Return explicit @ObjectType() response types; avoid returning raw Prisma models.

Prisma Conventions

• All schema changes go through Prisma migrations: yarn workspace @taskhub/api db:migrate.
• Never modify the database schema directly; always edit prisma/schema.prisma and create a migration.
• Run yarn workspace @taskhub/api db:generate after schema changes to regenerate the Prisma client.
• Use prisma/seed.ts for development seed data; keep seeds idempotent.
• Access Prisma through PrismaService (injected via NestJS DI), not the raw PrismaClient import.
• Use directUrl for direct database connections (bypasses connection pooling for migrations).

Database models:

User   — id, name, email (unique), password (bcrypt), role (USER|ADMIN), timestamps
Task   — id, title, description, status (TODO|IN_PROGRESS|DONE), priority (LOW|MEDIUM|HIGH),
         deadline, userId (FK → User), timestamps

Auth Conventions

• JWT strategy (jwt.strategy.ts) extracts the token from the Authorization: Bearer header.
• JwtAuthGuard wraps Passport JWT; apply it at resolver or method level.
• Passwords are hashed with bcryptjs before storing; never store plaintext passwords.
• JWT secret is sourced from JWT_SECRET environment variable; never hard-code it.
• Token payload contains { sub: userId, email }.

Validation Commands

Run before every commit:

yarn workspace @taskhub/api lint
yarn workspace @taskhub/api test

Run when changing Prisma schema:

yarn workspace @taskhub/api db:generate
yarn workspace @taskhub/api db:migrate

Full build check:

yarn workspace @taskhub/api build

Testing Conventions

• Unit tests live alongside source files or in test/ at the app root for e2e tests.
• Use Jest with @nestjs/testing to create isolated module contexts.
• Mock PrismaService in unit tests; do not hit a real database in unit tests.
• E2e tests in test/ use Supertest against a real NestJS app; run against a test database when available.
• Test file naming: *.spec.ts for unit tests, *.e2e-spec.ts for e2e tests.
• Cover service logic, guard behavior, and resolver input validation.

Environment Variables

• Store in .env locally (git-ignored).
• Never commit .env or secrets.
• Use .env.example to document required variables without values.

Code Quality

• Keep services focused: one service per feature domain.
• Extract shared logic (e.g., pagination helpers, error mappers) into common/ utilities.
• Use NestJS exception filters or throw HttpException / NestJS built-in exceptions; never throw raw Error from resolvers.
• Remove unused imports and decorators when touching a file.
• Keep DTO classes lean; add only the validation needed.

Continuous Learning Rule

If a task reveals a better convention, recurring mistake, or useful reminder specific to this API, update this SKILL.md in the same PR. Keep updates concise and actionable.