Remix Framework + MongoDB + Auth0 + Mongoose ODM Pipeline — CLAUDE.md Template

Overview

This CLAUDE.md Template provides a production-ready, copyable Claude Code prompt for building a Remix Framework app with MongoDB accessed via Mongoose ODM and authentication handled by Auth0. It covers architecture, file structure, authentication, database rules, validation, security, testing, deployment, and explicit things Claude must not do. This page is stack-specific and designed for developers seeking a ready-to-paste CLAUDE.md block for the Remix + MongoDB + Auth0 + Mongoose pipeline.

When to Use This CLAUDE.md Template

• You are implementing a Remix app that stores data in MongoDB via Mongoose ODM and uses Auth0 for authentication.
• You want a reproducible Claude Code prompt that enforces architecture, validation, security, and deployment constraints.
• You need a clear project structure and end-to-end guidance for production-ready Remix deployments.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a production-focused assistant that generates a Remix Framework + MongoDB + Auth0 + Mongoose ODM pipeline with secure defaults and clear constraints. Your output is the repository- and code-ready CLAUDE.md content for this stack.

Architecture rules:
- Use a Remix app layout with app/routes, app/components, app/styles, app/models (Mongoose models under a dedicated lib or models folder), and a single server module for DB/auth setup. Do not mix frameworks; keep Remix-centric conventions.
- Centralize Auth0 configuration in a server-side module and expose authentication state to loaders via cookies.
- Use Mongoose ODM for MongoDB models and a single mongoose connection lifecycle per process.
- All server actions must run on the Remix server, not in the browser.
- Do not generate global mutable state; favor dependency injection for services (db, auth, etc.).

File structure rules:
- remix-mongodb-auth0-mongoose-claude-md-template/
  app/
    components/
    routes/
    models/
    lib/
    entry.client.jsx
    entry.server.jsx
  config/
  .env.example
  package.json
  README.md

Authentication rules:
- Integrate Auth0 using environment variables: AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_CALLBACK_URL.
- Implement login/logout redirects and maintain session in secure, HTTP-only cookies.
- Validate and refresh JWTs on protected routes using the JWKS endpoint from AUTH0_DOMAIN.
- Do not expose client secrets in frontend code.

Database rules:
- Connect to MongoDB via mongoose.connect using MONGO_URI from env vars.
- Define models for User and a sample Doc (e.g., Post) with sensible validators and indexes.
- Do not bypass Mongoose schema validation or rely on client-side validation alone.

Validation rules:
- Use Joi (or an equivalent schema validator) to validate API inputs in Remix actions/loaders before touching the DB.
- Enforce required fields, data types, and length constraints.
- Do not trust client-provided IDs or tokens; always validate server-side.

Security rules:
- Use HTTPS, secure cookies, and HttpOnly cookies for sessions.
- Enable Helmet and relevant Remix security headers where applicable.
- Apply rate-limiting on authentication endpoints; protect against brute force.
- Do not embed secrets in frontend code or commit them to version control.

Testing rules:
- Unit tests for Mongoose models and validators.
- Integration tests for authentication flow with mocked Auth0 responses.
- End-to-end tests verifying protected routes and data access using a test MongoDB instance.
- Include test coverage checks in CI.

Deployment rules:
- Prepare a production Remix deployment (Vercel, Render, or similar) with environment variables for AUTH0 and MONGO_URI.
- Ensure the app connects to MongoDB Atlas or a managed MongoDB instance in production.
- Run build and start scripts in CI/CD; verify health endpoints post-deploy.

Things Claude must not do:
- Do not expose secrets in code or environment files in public repos.
- Do not bypass server-side validation or rely solely on client-side checks.
- Do not generate Prisma-based code for MongoDB workflows.
- Do not use insecure authentication flows or expose access tokens to the browser.
- Do not assume a relational database; MongoDB + Mongoose ODM is your data layer.

Recommended Project Structure

remix-mongodb-auth0-mongoose-claude-md-template/
  app/
    components/
    routes/
    models/
    lib/
    entry.client.jsx
    entry.server.jsx
  config/
  package.json
  .env.example
  README.md

Core Engineering Principles

• Explicit boundaries: keep Remix route logic, DB access, and auth separate.
• Security by default: secure cookies, server-side validation, least privilege access.
• Deterministic deployment: single source of truth in CLAUDE.md prompts and repo structure.
• Observability: structured logging, metrics hooks, and health checks for deployment readiness.
• Type- and schema-safety: validation at boundary layers and Mongoose schemas for data integrity.

Code Construction Rules

• All server code runs on Remix’s server context; avoid browser-only logic in actions/loaders that touches DB or tokens.
• Models must be defined with Mongoose schemas; never write raw Mongo queries without validation wrappers.
• Auth0 integration must verify tokens on the server and store only non-sensitive session data in cookies.
• Environment configuration must be read from process.env and never hard-coded.
• Use strict TypeScript or JSDoc typing for function signatures in server code.
• Follow a consistent coding style, with clear error handling and meaningful messages for failures.

Security and Production Rules

• HTTPS is mandatory for all endpoints; enforce secure cookies for sessions.
• CSRF protection through Remix loaders/actions patterns; avoid insecure stateful patterns on client.
• Token validation against Auth0 JWKS with rotation support; reject expired or invalid tokens.
• Limit data exposure by returning only necessary fields in API responses.
• Regularly rotate secrets and store them in a secure vault or environment management system.

Testing Checklist

• Unit tests for Mongoose models with validators and default values.
• Integration tests for auth flow using mocked Auth0 responses and token validation.
• End-to-end tests that cover login, protected routes, data creation, and data retrieval.
• CI workflow that runs tests, lints, and builds the Remix app for production.
• Smoke tests after deployment to verify connectivity to MongoDB and Auth0 callbacks.

Common Mistakes to Avoid

• Mixing client-side validation with server-side guarantees; always validate on the server.
• Storing sensitive data in frontend cookies or local storage.
• Hard-coding secrets or accidentally committing them to version control.
• Using Prisma for MongoDB workflows in a Mongoose-based pipeline.
• Omitting token rotation or improper JWKS handling for Auth0.

FAQ

What is this CLAUDE.md Template designed for?

It provides a complete Claude Code prompt for a Remix + MongoDB + Auth0 + Mongoose ODM pipeline, including a copyable CLAUDE.md block, structure, and rules.

How do I use the copyable CLAUDE.md Template?

Copy the contents of the large code block under Copyable CLAUDE.md Template and paste into CLAUDE.md in your repository. Follow the file structure and rules to ensure consistency.

Does Auth0 integration require server-side validation?

Yes. Token validation and session management must be performed on the server, with only non-sensitive session data stored in secure cookies.

What if I already have a Remix project?

Use this template as a blueprint for new routes, models, and authentication flows. Do not refactor existing patterns unless you ensure compatibility with Mongoose and Auth0 integration.

Where should I host the MongoDB connection?

Connect to MongoDB Atlas (or another managed instance) via MONGO_URI in environment variables; do not embed credentials in code.

Can I customize models or authentication providers?

Yes, but keep core patterns (Mongoose models, Auth0 validation, and Remix conventions) intact to preserve security and reliability.