NestJS + PlanetScale MySQL + Firebase Auth + Prisma Module Hook — CLAUDE.md Template

Overview

This CLAUDE.md Template page documents a stack specific blueprint for building a NestJS API that uses PlanetScale MySQL as the data store, Firebase Auth for authentication, and a Prisma ORM Module Hook. It provides a copyable CLAUDE.md block and concrete guidance for production-grade implementation with focus on security, testing, and maintainability.

When to Use This CLAUDE.md Template

• You need a strongly typed NestJS API backed by a PlanetScale MySQL cluster.
• You want Firebase Auth integrated for server side token verification and user management.
• You require a Prisma ORM Module Hook to centralize repository access and middleware-like behavior.
• You are setting up a CI/CD workflow with environment parity from development to production.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code, an AI coding assistant specialized for NestJS with PlanetScale MySQL, Firebase Auth, and Prisma Module Hook. Produce production-ready boilerplate, architecture notes, and a complete CLAUDE.md block that a developer can paste into their repository.

Architecture rules
- Use a modular NestJS API with a dedicated auth module, prisma module, and feature modules.
- All data access goes through a Prisma module hook to enforce authorized access and logging.
- Validation uses class-transformer and class-validator DTOs.
- Tokens are verified via Firebase Admin SDK on each request and set on the request context.
- Secrets live in a managed vault; do not log raw secrets.

File structure rules
- src/main.ts
- src/app.module.ts
- src/modules/auth/firebase-auth.module.ts
- src/modules/prisma/prisma.module.ts
- src/modules/prisma/prisma.service.ts
- src/modules/features/**/controllers/*.ts
- src/modules/features/**/services/*.ts
- src/hooks/prisma/prisma-hooks.ts
- prisma/schema.prisma
- .env

Authentication rules
- Validate Firebase ID tokens on every API call using the Firebase Admin SDK.
- Attach user payload to the request object; implement a Guard that enforces authentication and optional role checks.
- Never expose Firebase credentials to clients; use short lived tokens.

Database rules
- PlanetScale MySQL as the primary data source via Prisma client.
- Use a generated Prisma client per environment; connect using DATABASE_URL from the environment.
- Do not rely on migrations in production; use deploy-suitable workflows for PlanetScale per changes.

Validation rules
- Define DTOs for all inputs; apply class-validator rules; reject invalid payloads early with clear messages.
- Normalize and sanitize inputs before persistence.

Security rules
- Enforce HTTP headers via helmet; enable rate limiting;
- Do not log queriable secrets; mask sensitive fields in logs.
- Implement authorization checks in the Prisma module hook for resource ownership.

Testing rules
- Unit test services and guards; mock Firebase Admin SDK for auth tests.
- Integration tests cover auth flow, Prisma access, and module hooks.
- CI runs linting, type checks, unit and integration tests on push.

Deployment rules
- Environment variables: DATABASE_URL, FIREBASE_ADMIN_SDK_SECRET, FIREBASE_PROJECT_ID, JWT_PUBLIC_KEYS_URL.
- Use Prisma migrate deploy or PlanetScale schema management as appropriate for migrations.
- Ensure secret rotation and health checks on deployment.

Things Claude must not do
- Do not bypass authentication.
- Do not generate insecure defaults or leave secrets in code.
- Do not generate large monolithic files; keep modular boundaries clear.

Recommended Project Structure

src
├── main.ts
├── app.module.ts
├── config
│   └── app.config.ts
├── modules
│   ├── auth
│   │   ├── firebase-auth.module.ts
│   │   ├── firebase-auth.guard.ts
│   │   └── firebase-auth.service.ts
│   ├── prisma
│   │   ├── prisma.module.ts
│   │   ├── prisma.service.ts
│   │   └── prisma-client.ts
│   └── features
│       ├── users
│       │   ├── users.controller.ts
│       │   └── users.service.ts
│       └── posts
│           ├── posts.controller.ts
│           └── posts.service.ts
├── hooks
│   └── prisma
│       └── prisma-hooks.ts
└── dtos
    └── create-user.dto.ts

prisma
└── schema.prisma

Core Engineering Principles

• Explicit contracts and typed boundaries across modules.
• Separation of concerns and single source of truth for data access.
• Security first: validate tokens, authorize access, and minimize exposed surface.
• Declarative configuration and reproducible deployments.
• Testable by design: unit, integration, and simple end-to-end scenarios.

Code Construction Rules

• Use TypeScript and NestJS idioms for controllers, services, guards, and providers.
• Access data exclusively through a Prisma Module Hook to enforce consistent behavior.
• DTOs with class-validator and class-transformer for input validation.
• Environment-driven configuration; avoid hard coded values.
• Keep modules small and cohesive; prefer composition over inheritance.
• Do not rely on legacy global state; initialize instances through DI.

Security and Production Rules

• Validate every Firebase ID token server-side before processing requests.
• Mask sensitive data in logs; redact tokens and secrets.
• Enable rate limiting and proper CORS settings for API endpoints.
• Use PlanetScale deployment practices; avoid long running migrations in prod.
• Rotate service credentials and audit access to the secrets vault regularly.

Testing Checklist

• Unit tests for services and guards with mocks for Firebase Admin SDK.
• Integration tests for auth flow, Prisma access, and module hooks.
• CI: lint, type checks, unit tests, and integration tests on push; require passing before merge.
• End-to-end smoke tests to validate auth and data fetch paths.

Common Mistakes to Avoid

• Hardcoding credentials or tokens in code or repo.
• Skipping token verification or trusting client side auth for access control.
• Not centralizing data access in a Prisma Module Hook; inconsistent data handling.
• Overfetching data or exposing internal fields through API responses.
• Neglecting environment parity between development and production.

FAQ

• What is this CLAUDE.md Template for NestJS with PlanetScale and Firebase?

  It provides a pasteable blueprint to implement a NestJS API with PlanetScale MySQL, Firebase Auth, and Prisma Module Hook, including a ready CLAUDE.md block.

• Which environment variables are required?

  DATABASE_URL, FIREBASE_ADMIN_SDK_SECRET, FIREBASE_PROJECT_ID, and related Firebase config values must be supplied in the runtime environment.

• How is auth enforced?

  Firebase ID tokens are verified on each request via the Firebase Admin SDK; the user is attached to the request and access is controlled by guards.

• How should migrations be handled with PlanetScale?

  Plan migrations to leverage PlanetScale deploys and avoid blocking operations. Use prisma migrate deploy in CI where supported by the workflow.

• Where do I put Prisma related code?

  All Prisma related access resides in the Prisma Module and Hook, ensuring consistent transaction and logging behavior.