Next.js 16 + MariaDB + Stytch Auth + Sequelize ORM Enterprise Setup | CLAUDE.md Template

Overview

CLAUDE.md template for Next.js 16 + MariaDB + Stytch Auth + Sequelize ORM Enterprise Setup. This page provides a ready-to-paste CLAUDE.md block that guides Claude Code to generate, scaffold, and validate an enterprise-grade Next.js application with MariaDB, Stytch onboarding/multi-factor authentication, and Sequelize ORM integration. The direct answer: use this CLAUDE.md Template to configure architecture, coding standards, and automated tests for the stack.

When to Use This CLAUDE.md Template

• Rapidly bootstrap an enterprise Next.js 16 project with MariaDB as the data store.
• Enforce Stytch-based authentication flow (passwordless or MFA) and user provisioning.
• Initialize Sequelize models and migrations for reliable DB interactions.
• Define production-grade architecture, security, and deployment rules for the stack.
• Share a reproducible blueprint across teams and CI pipelines.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Enterprise full-stack architect for Next.js 16 + MariaDB + Stytch Auth + Sequelize ORM in Claude Code.

Architecture rules:
- Use a strict layered architecture: services, data access, UI, and infra (auth and DB).
- Centralized config with environment parity between local, staging, and prod.
- Prefer App Router (Next.js 13+) with server components where possible; isolate API routes.
- Use Sequelize for MariaDB ORM with explicit migrations and seed data.
- Implement token-based authentication using Stytch; separate session management from app logic.

File structure rules:
- Do not generate Prisma-related files; use Sequelize models and migrations.
- Place server-side code under apps/enterprise-next-app/src and apps/enterprise-next-app/api.
- Place UI code under apps/enterprise-next-app/app.
- Use a single source of truth for env vars in .env files per environment.

Authentication rules:
- Integrate Stytch SDK with proper secret management (env vars: STYTCH_PROJECT_ID, STYTCH_API_KEY).
- Enforce passwordless or MFA flows for sign-in; implement device trust where feasible.
- Do not embed secret keys in client-side code.

Database rules:
- MariaDB as the primary DB; use Sequelize models with migrations in db/migrations.
- Use strict data types and constraints; enforce referential integrity.
- Use connection pooling and proper time zone handling.

Validation rules:
- Validate all inputs server-side; rely on Sequelize validators where possible.
- Use Zod or Joi on API boundaries if allowed; ensure error messages do not leak secrets.

Security rules:
- Enable CSRF protection for state-changing endpoints.
- Use HTTP-only secure cookies for sessions; set proper CORS policy.
- Never log secrets or database credentials; rotate keys regularly.

Testing rules:
- Unit test Sequelize models and validators; integration test API routes and auth flows.
- Mock Stytch interactions in tests; use test DB instances.
- Include end-to-end tests for login flows in staging.

Deployment rules:
- Use GitHub Actions for CI/CD; deploy to Vercel or AWS with environment promotion.
- Ensure database migrations run on deploy; store migrations in db/migrations and apply via CLI in CI.
- Enable feature flags for new stack components and blue/green deploys.

Things Claude must not do:
- Do not generate insecure secrets in code.
- Do not bypass migrations or seed data in production.
- Do not implement custom auth flows outside Stytch’s recommended patterns.
- Do not reveal actual secrets; redact in logs and docs.

Recommended Project Structure

apps/enterprise-next-app/
├── app/                    # Next.js App Router
│   ├── layout.tsx
│   ├── page.tsx
│   └── ...
├── src/                    # Server-side sources
│   ├── lib/                # shared utilities
│   ├── db/                 # Sequelize setup and models
│   │   ├── models/         # Sequelize models
│   │   ├── migrations/     # Sequelize migrations
│   │   └── index.ts        # sequelize init
│   ├── services/           # business logic services
│   ├── routes/             # API routes
│   └── middleware/           # security, auth, etc.
├── configs/                # environment configuration
├── .env.example            # environment template
├── package.json            # project dependencies
├── tsconfig.json           # TS config
└── next.config.js          # Next.js config

Core Engineering Principles

• Explicit architecture: clear separation of concerns between UI, API, and data layers.
• Deterministic deployments: immutable infrastructure with migration-based DB changes.
• Environment parity: local, staging, and production mirror each other.
• Type safety: use TypeScript and strict Sequelize typing; guard API surfaces with validators.
• Security by default: apply CSRF, proper CORS, and secure cookies from the start.

Code Construction Rules

• Use Sequelize ORM with MariaDB; define models in models/* and migrations in migrations/*.
• Configure Next.js 16 App Router; keep server components isolated from client components.
• Store secrets in environment variables; never hard-code in source.
• Use absolute imports and path aliases for maintainability.
• Validate inputs at API boundaries with server-side checks.

Security and Production Rules

• Enable Stytch-based authentication with secret management; require MFA for admin users where possible.
• Use HTTPS, CSRF protection, and secure cookies; configure strict CORS for API endpoints.
• Rotate credentials periodically and audit access logs; do not log secrets.

Testing Checklist

• Unit tests for Sequelize models and validators; mock DB where appropriate.
• Integration tests for API endpoints including auth flows; verify error paths.
• End-to-end tests for sign-in/up with Stytch in a staging environment.
• CI/CD checks to run migrations and deploy in staging before prod.

Common Mistakes to Avoid

• Mixing ORM layers (Sequelize) with raw queries without proper typing.
• Hard-coding secrets or using insecure auth flows.
• Skipping migrations in production or ignoring data seeding.
• Neglecting environment parity or over-sharing environment variables.

FAQ

• Q: What stack does this CLAUDE.md Template cover?
  A: Next.js 16, MariaDB, Stytch Auth, Sequelize ORM for enterprise setups.
• Q: Does it include deployment instructions?
  A: Yes, including CI/CD, migrations, and environment promotion steps.
• Q: Where are secrets stored?
  A: In environment variables, not in code or logs.
• Q: Can I substitute Prisma for Sequelize?
  A: This CLAUDE.md Template is tailored for Sequelize with MariaDB. Prisma would require structural changes.
• Q: How should I extend the template for additional services?
  A: Follow the architecture rules and add services under the src/services and apps paths with proper migrations.