CLAUDE.md Template: SvelteKit + TimescaleDB + Custom Token Session + Prisma ORM Pipeline

Overview

Direct answer: This CLAUDE.md Template provides a complete, copyable CLAUDE.md block tailored for a production-grade SvelteKit app that uses TimescaleDB for time-series data, Prisma ORM for data access, and a custom token-based session pipeline. It is designed for Claude Code to generate, customize, and deploy in a predictable way.

The stack covered here combines SvelteKit with TypeScript, TimescaleDB hypertables, Prisma ORM, and a secure, token-based session flow backed by HttpOnly cookies and rotating refresh tokens.

When to Use This CLAUDE.md Template

• You are building a production-grade SvelteKit app that ingests time-series data into TimescaleDB.
• You want a repeatable Prisma ORM pipeline across routes and APIs.
• You require a secure, token-based session model with HttpOnly cookies and refresh rotation.
• You need a self-contained CLAUDE.md template that your team can copy-paste and customize.

Copyable CLAUDE.md Template

# CLAUDE.md
Role: You are a senior full-stack engineer building a production-grade SvelteKit app with TimescaleDB for time-series data, Prisma ORM for data access, and a custom token-based session flow. The goal is a secure, scalable, and maintainable codebase that Claude Code can generate incrementally.

Architecture rules:
- Build a modular SvelteKit app (TypeScript) with clear boundaries between routes, services, and data access.
- Use Prisma ORM to talk to PostgreSQL/TimescaleDB; hypertables are defined in migrations and accessed via Prisma client.
- Implement a custom token-based session using HttpOnly cookies; refresh tokens rotate and are stored securely.
- All server-side data access must go through a minimal API surface; clients must not talk directly to the DB.
- Use a single source of truth for user identities and tokens; centralize configuration and secrets in environment variables.

File structure rules:
- /src/app.html and /src/app.css (or +layout.svelte for UI scaffolding)
- /src/hooks.server.ts for session initialization and per-request auth
- /src/lib/db.ts to initialize a singleton PrismaClient
- /src/routes/api/auth/**
- /src/routes/api/me and /src/routes/api/measurements/**
- /src/routes/(protected)/** for authenticated pages
- /prisma/schema.prisma with models: User, Session, Measurement
- /prisma/migrations for SQL migrations, including hypertable creation
- /src/lib/utils/validation.ts for zod-based payload validation
- /scripts for migrations/seeding
- Use environment-based configuration; never hardcode secrets

Authentication rules:
- Tokens are JWTs signed with a symmetric secret (HS256); rotate access and refresh tokens
- Access token short-lived; refresh via a secure HttpOnly cookie
- Passwords hashed with bcrypt; store hashed passwords and salts
- On login, issue accessToken (5-15 min) and refreshToken (7 days); on refresh, issue new tokens
- Validate token issuer, audience, and expiry on protected endpoints
- Logout clears cookies and invalidates refresh token

Database rules:
- TimescaleDB hypertables for time-series data; a separate users table stores credentials
- Prisma models: User, Session, Measurement
- Use raw SQL migrations to create hypertables when needed; queries must respect hypertable structures
- All queries should be type-safe via Prisma client

Validation rules:
- Validate inputs with a strict schema (Zod) and return precise errors
- Validate JWTs and ensure claims match expected issuer/audience
- Enforce input length, formats, and required fields

Security rules:
- Use HTTPS; set Secure and HttpOnly on cookies; SameSite=Strict
- Rate-limit login attempts; monitor for brute force
- Do not leak stack traces or internal details in errors
- Keep secrets in environment variables; do not commit them
- Do not expose raw Prisma or DB errors to clients
- Use CSRF protection for cookie-based auth on state-changing endpoints

Testing rules:
- Unit tests for Prisma data access; integration tests for API/auth flows
- End-to-end tests for login/logout and typical measurement ingestion
- Use Vitest or Jest; run in CI with coverage checks
- Mock external services; run tests against a test TimescaleDB instance

Deployment rules:
- Dockerfile and docker-compose for dev; production uses a stack with PostgreSQL/TimescaleDB
- Prisma generate and migrate during deployment; run migrations in CI
- Environment variables drive config; secrets pulled from a vault/CI secrets manager
- Observability: logs, metrics, and basic tracing

Things Claude must not do:
- Do not access real secrets; never embed credentials in code
- Do not persist tokens in localStorage or insecure storage
- Do not bypass migrations or alter the database schema without migrations
- Do not generate non-TS or non-SvelteKit code
- Do not rely on unsupported databases (TimescaleDB is Postgres-based)
- Do not degrade accessibility or usability of the app

Recommended Project Structure

my-app/
  src/
    app.html
    hooks.server.ts
    lib/
      db.ts
    routes/
      api/
        auth/
          login.ts
          refresh.ts
        measurements/
          index.ts
        users/
          me.ts
      (protected)/
        +layout.svelte
        +page.svelte
  prisma/
    schema.prisma
  scripts/

Core Engineering Principles

• Type safety and explicit contracts across API boundaries
• Single source of truth for data and config
• Security by default with proper defaults and fail-safe sanitization
• Observability through structured logs and metrics
• Maintainable and incremental code generation with Claude Code
• Performance-conscious data access, especially for hypertables

Code Construction Rules

• Use TypeScript throughout; strict mode enabled
• Define Prisma models and use the generated client for all DB access
• Split business logic into services and route handlers; avoid mixing concerns
• Validate inputs with strict schemas before processing
• Store secrets in environment variables; do not hardcode
• Access TimescaleDB hypertables through ORM navigation when possible; use raw SQL for hypertable creation
• Ensure all protected endpoints check authentication state
• Do not implement DB-like logic in the UI layer

Security and Production Rules

• Enable HTTPS in all environments
• Use HttpOnly, Secure cookies with SameSite=Strict
• Rotate access tokens and refresh tokens; invalidate on logout
• Limit login attempts and monitor anomalies
• Hide internal errors from clients; surface friendly messages
• Require migrations to be applied in production before usage
• Limit Prisma query complexity; guard against heavy queries

Testing Checklist

• Unit tests for data models and utility functions
• Integration tests for API/auth endpoints
• End-to-end tests for login, token refresh, and data ingestion
• CI pipeline runs migrations and lints; ensures type safety

Common Mistakes to Avoid

• Skipping hypertable migrations or bypassing Prisma for hypertables
• Storing tokens in local storage or insecure cookies
• Overexposing internal errors to clients
• Neglecting environment-based config across environments

FAQ

What stack does this CLAUDE.md Template cover?

SvelteKit with TimescaleDB for time-series data, Prisma ORM for data access, and a custom token-based session flow.

How should I structure the project to use this template?

Follow the Recommended Project Structure block in the CLAUDE.md block and adapt file names to your domain.

How is authentication handled?

Token-based sessions with HttpOnly cookies and rotation via refresh tokens.

How do I deploy this template?

Use Docker and a CI/CD pipeline; ensure TimescaleDB instance is accessible and migrations run.

Is TimescaleDB hypertable support included?

Yes; hypertable creation is managed via migrations and Prisma client usage.