Remix Framework + ScyllaDB + Custom JWT Auth + Scylla Driver Framework — CLAUDE.md Template

Overview

The CLAUDE.md template provides a copyable Claude Code blueprint for building a Remix Framework application backed by ScyllaDB, with a custom JWT authentication flow and a Scylla Driver integration. It targets TypeScript-based Remix projects and emphasizes secure, production-ready patterns.

Direct answer: This CLAUDE.md template gives you a ready-to-paste Claude Code scaffold to implement Remix + ScyllaDB + JWT, including auth middleware, DB adapters, route patterns, and deployment guidance.

When to Use This CLAUDE.md Template

• You are starting a new Remix app that uses ScyllaDB as the data store.
• You need a centralized, typed approach for JWT-based authentication with cookie-based sessions.
• You want a clean separation between Remix route logic, business services, and the Scylla driver layer.
• You require a reproducible CLAUDE.md setup that you can paste into Claude Code to generate a working skeleton.

Copyable CLAUDE.md Template

# CLAUDE.md
Project Role: You are a Remix Framework engineer who integrates ScyllaDB via the Scylla Driver and implements a custom JWT authentication flow. Produce a production-ready code scaffold with clear boundaries between Remix routes, services, and data access.
Architecture Rules:
- Use a layered architecture: Remix route handlers (loaders/actions) call into a services layer; data access via a dedicated Scylla driver adapter; configuration provided through environment-based config.
- TypeScript-first: all code is TypeScript; strictly typed inputs/outputs; prefer interfaces and types over any.
- Stateless API surface: route handlers should be side-effect free except when performing IO; business logic resides in services.
- Use dependency injection where possible; keep the driver and config instances injectable for testing.
File Structure Rules:
- Only include folders relevant to Remix + ScyllaDB + JWT: app/, scylla/, jwt/, tests/, and minimal config files.
- Place DB adapters under scylla/driver.ts and scylla/config.ts; place services under scylla/services/ or app/services/.
- Route components go under app/routes/; UI components under app/components/.
- Use a dedicated tests/ directory for unit/integration tests.
Authentication Rules:
- Implement JSON Web Token authentication with a shared secret (JWT_SECRET) sourced from environment variables.
- Use HTTP-Only cookies to store access/refresh tokens; validate tokens on each request with a middleware-like guard.
- Enforce short-lived access tokens (eg 15 minutes) and rotate via refresh tokens.
- Do not expose secrets to the client.
Database Rules:
- Connect to ScyllaDB via the Scylla Driver; use prepared statements; parameterize all queries.
- Do not construct SQL/CQL by string concatenation; always use bound parameters.
- Use a single, typed data access layer and export clear query helpers.
Validation Rules:
- Validate all external inputs using a typed schema library (eg Zod) before processing.
- Use strict mode schemas and meaningful error messages.
Security Rules:
- Store secrets securely; never log sensitive token data.
- Enforce HTTPS and HttpOnly cookies; set SameSite=Strict for cookies in production.
- Implement input sanitization and CSRF protection for forms.
Testing Rules:
- Unit tests for services and adapters; integration tests that exercise DB access with a local ScyllaDB instance or a test container.
- End-to-end tests simulate session creation, protected route access, and token rotation.
- CI should run tests on push and pull requests.
Deployment Rules:
- Build in production mode; bundle with Remix optimizations.
- Ensure env vars (JWT_SECRET, SCYLLA_CONTACT_POINTS, etc.) are provided in the deployment environment.
- Use a resilient hosting platform and enable TLS termination.
Things Claude Must Not Do:
- Do not bypass authentication checks or expose secrets to clients.
- Do not generate raw string-based CQL in application code; use prepared statements.
- Do not degrade security by creating insecure cookies or disabling TLS in production.

Recommended Project Structure

remix-scylla-app/
  app/
    routes/
    components/
    lib/
    entry.client.tsx
    entry.server.tsx
    root.tsx
  scylla/
    config.ts
    driver.ts
    services/
      userService.ts
      authService.ts
  jwt/
    auth.ts
  tests/
  .env
  package.json
  tsconfig.json

Core Engineering Principles

• Explicit typing and TypeScript-first development.
• Clear separation of concerns: routes, services, data access, and auth.
• Defensive programming with input validation and strict schemas.
• Principle of least privilege for DB access and secure secret management.
• Observability: structured logging, metrics, and tracing where appropriate.

Code Construction Rules

• Use Remix route loaders/actions for IO; keep business logic in services.
• Every DB call must use prepared statements and bound parameters via Scylla Driver.
• Configure environment-based settings (ENV vars) and avoid hardcoding secrets.
• Use Zod or equivalent for input validation; export type-safe schemas.
• JWT flow: issuer, audience, expiry, rotation; store tokens in httpOnly cookies.
• Consistent naming conventions for modules, services, adapters, and routes.
• Graceful error handling with user-friendly messages and error boundaries.

Security and Production Rules

• Enforce HTTPS, HttpOnly and Secure cookies in production; SameSite=Strict.
• Rotate JWT keys and implement token revocation strategies as needed.
• Do not log sensitive token payloads or secrets; redact when necessary.
• Configure ScyllaDB TLS and client-side certificate validation if supported.
• Audit trails for authentication events; guard against brute force attempts (rate limiting).

Testing Checklist

• Unit tests for services and adapters with mock ScyllaDriver.
• Integration tests that exercise real ScyllaDB connections (local or containerized).
• End-to-end tests covering login, protected routes, and token rotation.
• CI pipelines to run tests and linting on PRs and merges.

Common Mistakes to Avoid

• Assuming the JWT secret is safe to store in client-side code.
• Using string concatenation for CQL; not using prepared statements.
• Skipping input validation or over-relying on client-side validation.
• Neglecting token rotation and proper refresh token handling.
• Forgetting to rotate secret keys or revoking compromised tokens.

FAQ

What stack does this CLAUDE.md Template cover?

Remix Framework + ScyllaDB + Custom JWT Auth + Scylla Driver Framework, with Claude Code guidance.

What files are created by this template?

A Remix app scaffold under app/, Scylla driver adapters under scylla/, JWT utilities under jwt/, tests/ and configuration files for deployment.

How do I customize JWT settings?

Configure JWT_SECRET, issuer, audience, and token lifetimes in environment variables; Claude Code will reflect these in the template.

Is this compatible with Remix App Router?

Yes. The template targets Remix with the App Router and demonstrates loaders/actions integration with the Scylla driver.

How should I deploy?

Build in production mode, provide required env vars, enable TLS, and deploy to a Node.js hosting platform or container-based service.