Nestjs Prisma Development

NestJS + Prisma Development Skill

Project Structure

apps/api/
├── src/
│   ├── app.module.ts          # Root module (imports all feature modules)
│   ├── main.ts                # Bootstrap: ValidationPipe, CORS, Helmet, Swagger, Pino
│   ├── auth/                  # Authentication & authorization (JWT, OAuth, OTP, RBAC)
│   ├── common/                # Shared: filters, interceptors, middleware, logger
│   ├── config/                # ConfigModule wrapper
│   ├── health/                # Health check (/api/health)
│   ├── mail/                  # Email service (Handlebars templates, OTP, welcome)
│   ├── match/                 # Match management & events
│   ├── prisma/                # PrismaService (driver adapter with pg.Pool)
│   ├── registration/          # Teams & players CRUD + CSV import (3 controllers)
│   ├── regulation/            # Season-scoped key-value regulations
│   ├── roster/                # Team-player assignments & jersey numbers
│   ├── scheduling/            # Round-robin schedule generation
│   ├── search/                # Global search across all entities
│   ├── season/                # Season CRUD & team registration workflow
│   ├── stadium/               # Stadium CRUD
│   ├── standings/             # League table, top scorers, card/team stats, exports
│   ├── upload/                # Image upload (Multer, 5MB, JPEG/PNG/WebP/GIF)
│   └── users/                 # Admin user management
├── prisma/
│   ├── schema.prisma          # 12 models, 10 enums
│   ├── seed.ts                # Master seeder (chains all seed scripts)
│   ├── seed-teams.ts          # 10 V-League teams with stadium mappings
│   ├── seed-players.ts        # 100+ randomized Vietnamese + foreign players
│   ├── seed-stadiums.ts       # 15 stadiums
│   ├── verify-demo-users.ts   # Ensure 5 demo role accounts exist
│   ├── register-teams-to-season.ts
│   ├── cleanup-stale-matches.ts
│   └── migrations/            # 13 migrations
└── test/                      # E2E specs (Supertest)

Core Technologies

Global Infrastructure (main.ts)

// Bootstrap configuration (already applied globally)
app.setGlobalPrefix('api'); // All routes: /api/...
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true, // Strip unknown props
    forbidNonWhitelisted: true, // Reject unexpected props
    transform: true, // Auto-transform to DTO classes
    transformOptions: { enableImplicitConversion: true }, // "1" → 1
  }),
);
app.useGlobalFilters(new HttpExceptionFilter()); // Unified error shape
app.useGlobalInterceptors(new LoggingInterceptor()); // Perf timing + Server-Timing header
app.enableCors({ origin: CORS_ORIGIN, credentials: true });

// Static assets
app.useStaticAssets(join(process.cwd(), 'uploads'), { prefix: '/uploads/' });

// Swagger at /api/docs — 5 tags declared in DocumentBuilder
// Additional tags auto-discovered from @ApiTags() on controllers
SwaggerModule.setup('docs', app, document);

Global Guards (via APP_GUARD)

Interceptors

Filters & Middleware

Prisma Schema (12 Models, 10 Enums)

Enums

Models

Schema Conventions

model EntityName {
  id        String   @id @default(uuid()) @db.Uuid   // Always UUID
  fieldName String   @map("field_name")               // snake_case in DB
  status    EnumType @default(VALUE)
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")
  @@map("table_name")                                 // snake_case table
}

IMPORTANT: All PK and FK use @db.Uuid. Prisma 7 uses @prisma/adapter-pg driver adapter with raw pg.Pool.

Prisma Relation Names

WARNING: The relation field on Team and Player for the join table is named roster (from TeamPlayer[]), NOT teamPlayers. Always use roster in include and where:

// ✅ Correct
this.prisma.player.findMany({ include: { roster: { include: { team: true } } } });
// ❌ Wrong
this.prisma.player.findMany({ include: { teamPlayers: true } });

Prisma Enum Casting

TIP: When assigning string literals to Prisma-generated enum fields, use as never:

position: dto.position as never,
playerType: (dto.playerType ?? 'DOMESTIC') as never,

All Modules & Endpoints

1. AuthModule (/api/auth) — 19 endpoints

2. RegistrationModule (/api/teams, /api/players) — 11 endpoints

NOTE: The CSV import endpoint is in a separate PlayersImportController (players-import.controller.ts), not in PlayersController.

3. MatchModule (/api/matches) — 6 endpoints

4. SchedulingModule (/api/schedule) — 3 endpoints

5. SeasonModule (/api/seasons) — 11 endpoints

6. StadiumModule (/api/stadiums) — 5 endpoints

7. RosterModule (/api/teams/:teamId/roster) — 4 endpoints

8. RegulationModule (/api/seasons/:seasonId/regulations) — 5 endpoints

9. StandingsModule (/api/standings) — 12 endpoints

10. UsersModule (/api/users) — 4 endpoints (ADMIN only)

11. UploadModule (/api/upload) — 1 endpoint

12. SearchModule (/api/search) — 1 endpoint

13. HealthModule (/api/health) — 1 endpoint

14. MailModule (internal service, no controller)

• sendEmailVerificationOtp, sendPasswordResetOtp, sendWelcomeEmail
• Dev mode: MAIL_SKIP_SEND=true logs OTP to console
• Handlebars templates: email-verification.hbs, password-reset.hbs, welcome.hbs

15. PrismaModule (internal service)

• PrismaService extends PrismaClient with @prisma/adapter-pg driver adapter
• Lifecycle: onModuleInit → $connect(), onModuleDestroy → $disconnect()

Guards & Decorators

Guards

Decorators

Strategies

Cross-Module Dependencies

MatchModule → imports StandingsModule, RegulationModule
  - StandingsService: auto-recalculate on match FINISHED
  - RegulationHelper: MAX_GOAL_TIME validation

RegistrationModule → imports RegulationModule
  - RegulationHelper: MIN_AGE, MAX_AGE validation

RosterModule → imports RegulationModule
  - RegulationHelper: MAX_ROSTER, MAX_FOREIGN_PLAYERS validation

RegulationModule → exports RegulationService, RegulationHelper
  - RegulationHelper.getNumericValue(seasonId, key, fallback)

Common Module (src/common/)

DTO & Validation Patterns

// Create DTO
export class CreateTeamDto {
  @ApiProperty({ description: 'Team name', example: 'Hoàng Anh Gia Lai' })
  @IsString()
  @IsNotEmpty()
  name: string;

  @ApiPropertyOptional({ enum: TeamStatus, default: TeamStatus.ACTIVE })
  @IsOptional()
  @IsEnum(TeamStatus)
  status?: TeamStatus;
}

// Update DTO (partial of Create)
export class UpdateTeamDto extends PartialType(CreateTeamDto) {}

// Barrel export: dto/index.ts
export * from './create-team.dto';
export * from './update-team.dto';

Testing

23 test suites covering services, controllers, and E2E.

Test Pattern

describe('ModuleNameService', () => {
  let service: ModuleNameService;
  let prisma: PrismaService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        ModuleNameService,
        {
          provide: PrismaService,
          useValue: {
            modelName: {
              findMany: jest.fn(),
              findUnique: jest.fn(),
              create: jest.fn(),
            },
          },
        },
      ],
    }).compile();
    service = module.get(ModuleNameService);
    prisma = module.get(PrismaService);
  });
});

Auth Service Tests: jest.mock('bcrypt') at module level

E2E Tests: test/*.e2e-spec.ts with Supertest

Environment Variables

DATABASE_URL="postgresql://user:password@localhost:5432/vleague"
PORT=8080
CORS_ORIGIN=http://localhost:5173
JWT_SECRET=your-secret
JWT_REFRESH_SECRET=your-refresh-secret
JWT_EXPIRATION=15m
JWT_REFRESH_EXPIRATION=7d
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USER=...
MAIL_PASS=...
MAIL_FROM=noreply@vleague.local
MAIL_SKIP_SEND=true              # Dev: log OTP to console
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_CALLBACK_URL=http://localhost:8080/api/auth/google/callback
FACEBOOK_APP_ID=...
FACEBOOK_APP_SECRET=...
FACEBOOK_CALLBACK_URL=http://localhost:8080/api/auth/facebook/callback
FRONTEND_URL=http://localhost:5173

Common Commands

cd apps/api
pnpm dev                         # Start dev server (watch mode)
pnpm test                        # Unit tests (23 suites)
pnpm test:e2e                    # E2E tests
pnpm test:cov                    # Coverage report
pnpm dlx prisma migrate dev      # Create migration
pnpm dlx prisma generate         # Generate Prisma client
pnpm dlx prisma studio           # Open Prisma Studio GUI
pnpm run db:seed                 # Seed database
pnpm lint                        # ESLint

Notable Patterns

1. Prisma 7 Driver Adapter: Uses @prisma/adapter-pg with raw pg.Pool instead of binary engine
2. Vietnamese messages: All user-facing error messages in Vietnamese
3. CSV export with BOM: toCsv() helper prepends \uFEFF for Excel Vietnamese support
4. Structured error codes: AUTH_EMAIL_EXISTS, AUTH_OTP_INVALID, etc. for deterministic client handling
5. Device-aware sessions: Refresh tokens track userAgent, ipAddress, deviceName, lastUsedAt
6. OAuth account linking: Google/Facebook auto-link to existing email; users can set password post-OAuth
7. WebSocket deps present: @nestjs/websockets + socket.io in deps but no gateway implemented yet
8. Regulation-driven rules: Core limits (age, roster, foreign players, goal time) configurable per-season
9. RegulationHelper fallback: DB value → defaults → hardcoded fallback
10. Standings computed live: From match events, not from Standing model directly

Converted and distributed by TomeVault — claim your Tome and manage your conversions.