Remix Framework + Amazon Aurora v2 + AWS Cognito + Prisma ORM Boilerplate — CLAUDE.md Template

Overview

CLAUDE.md template for Remix Framework + Amazon Aurora v2 + AWS Cognito + Prisma ORM provides a copyable Claude Code blueprint you can paste into CLAUDE.md. It describes a ready-to-implement boilerplate for building secure, scalable full-stack applications with Remix on the frontend, Aurora PostgreSQL v2 on the database, Cognito for authentication, and Prisma as the ORM.

Direct answer: This CLAUDE.md Template is a precise, stack-specific instruction block that defines project role, architecture, file layout, authentication, database, validation, security, testing, deployment, and Claude usage constraints.

When to Use This CLAUDE.md Template

• Starting a new Remix project that uses Aurora PostgreSQL v2 and Cognito for auth
• Standardizing boilerplate across teams for this exact stack
• Creating a reproducible Claude Code instruction set to speed onboarding
• Documenting architectural rules to prevent drift during feature work

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Senior full-stack engineer building a Remix Framework boilerplate with Aurora v2 PostgreSQL, Cognito, and Prisma ORM.

Architecture rules:
- Use Aurora PostgreSQL v2 as the primary database
- Prisma ORM for data access; migrations via prisma migrate
- Cognito for authentication; session tokens stored in httpOnly cookies
- Remix server routes to access data; client code must not bypass server
- Secrets loaded from environment variables; never hard-coded
- TLS for database connections and API endpoints

File structure rules:
- prisma/schema.prisma defines data models and data source
- app/ holds Remix routes and components
- services/ contains business logic and data access wrappers
- lib/ contains shared utilities and helpers
- prisma/migrations/ stores Prisma migrations
- .env.example with required variables

Authentication rules:
- Cognito user pool for sign-in; app client configured for PKCE on web
- Server-side token validation for protected routes
- Access tokens used for API calls; refresh tokens rotated securely

Database rules:
- Aurora PostgreSQL v2 with TLS enabled
- Use Prisma migrations for schema changes; avoid manual edits in production
- Enforce proper foreign keys and indexes for performance

Validation rules:
- Use zod schemas for request validation; return concise, actionable errors
- Validate data types, ranges, and required fields at the boundary

Security rules:
- Enable CSRF protection for Remix forms
- Use secure, httpOnly cookies; sameSite=Lax or strict as appropriate
- Do not log sensitive data; mask tokens in logs

Testing rules:
- Unit tests for utilities and validators
- Integration tests for auth flows with Cognito mocks
- End-to-end tests for critical paths (login, signup, protected routes)

Deployment rules:
- Deploy to AWS; Aurora in private subnets; Cognito in same region
- Use CI/CD with environment-specific configurations
- Ensure migrations run in production via prisma migrate deploy

Things Claude must not do:
- Do not bypass authentication checks
- Do not access the database directly from the client
- Do not store secrets in source control
- Do not rely on non-production endpoints in prod

Recommended Project Structure

RemixAuroraCognitoPrismaBoilerplate/
  .env.example
  package.json
  prisma/
  prisma/schema.prisma
  prisma/migrations/
  app/
    root.jsx
    entry.client.jsx
    entry.server.jsx
    routes/
      index.jsx
      auth/
        login.jsx
        signup.jsx
      api/
        users.jsx
  public/
  remix.config.js

Core Engineering Principles

• Explicitness over ambiguity in code and rules
• Single source of truth for configuration and data access
• Testability with clear unit and integration tests
• Security-first mindset in auth, data, and deployment
• Performance-conscious patterns and proper resource scoping

Code Construction Rules

• Stick to Remix conventions for routes and loaders/actions
• Prisma models must reflect Aurora PostgreSQL data types
• Authentication flow uses Cognito with PKCE and httpOnly cookies
• Environment variables are sourced from .env files or CI secrets
• Do not embed secrets; never commit credentials
• Use migrations for schema changes and guard against rollback risks

Security and Production Rules

• Enable TLS on all endpoints; enforce secure cookies
• CSRF protection for forms; validate tokens on protected routes
• Audit logging should not expose secrets; rotate keys regularly
• Database access should go through Prisma with parameterized queries

Testing Checklist

• Unit tests for utilities and validators
• Integration tests for Prisma queries and Cognito integration
• End-to-end tests for login, signup, and protected routes
• Migration tests to ensure schema changes apply cleanly
• Performance tests on common read paths

Common Mistakes to Avoid

• Hard-coding environment values or secrets
• Skipping migrations in production
• Relying on client-side validation for security-critical checks
• Using non-production Cognito resources in production

FAQ

• What is this CLAUDE.md Template for Remix + Aurora + Cognito + Prisma? A copyable Claude Code blueprint for a full-stack boilerplate with stack-specific rules.
• Can I adapt this for other databases? The template targets Aurora PostgreSQL v2; adapt Prisma datasource if needed and update migrations accordingly.
• How do I deploy? Use CI to push env vars securely, run prisma migrate deploy, and deploy Remix app to your host of choice with Aurora in private subnets.
• How is authentication handled? Cognito User Pools manage sign-in; server validates tokens and issues session cookies.
• Where are secrets stored? In AWS Secrets Manager or CI secrets; never in code or repos.