SvelteKit + ClickHouse + Clerk Auth CLAUDE.md Template

Overview

CLAUDE.md template for a production-ready SvelteKit application that uses ClickHouse for telemetry storage, Clerk for authentication, and the ClickHouse Client library for telemetry ingestion. This is a copyable CLAUDE.md template page designed to accelerate boilerplate setup while enforcing a disciplined, production-ready structure for Claude Code users.

Direct answer: This CLAUDE.md template provides a ready-to-paste block for building a secure, observable SvelteKit app with server-side telemetry written to ClickHouse and protected by Clerk authentication.

When to Use This CLAUDE.md Template

• Starting a new SvelteKit project that requires user authentication via Clerk.
• Setting up server-side telemetry ingestion to ClickHouse with proper separation of concerns.
• Creating a repeatable CLAUDE.md template pattern for Claude Code templates in this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude, a production-ready CLAUDE.md template assistant for a SvelteKit app using ClickHouse for telemetry, Clerk for authentication, and the ClickHouse Client for data ingestion. Output must be concrete, actionable, and paste-ready.

Architecture rules:
- Target runtime: Node 18+ with adapter-node for deployment.
- All telemetry ingestion must occur on the server; do not send data from the browser to the database directly.
- Secrets (ClickHouse credentials, Clerk keys) must live in environment variables; never commit them.
- Separate concerns: authentication, telemetry ingestion, and business logic in distinct modules.
- Validate Clerk sessions on protected endpoints and guard API routes with server-side checks.
- Use the ClickHouse Client library with parameterized/structured inserts; avoid string-concatenated SQL.

File structure rules:
- src/lib/clerk.ts: Clerk client initialization and helper utilities
- src/lib/db.ts: ClickHouse client wrapper and safe query helpers
- src/routes/api/telemetry.ts: server-only telemetry ingestion endpoint
- src/routes/api/auth.ts: Clerk-based auth helpers and session validation
- src/hooks.server.ts: load and expose Clerk session on the server for route guards
- .env.example: required environment variables (CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLERK_API_KEY, etc.)

Authentication rules:
- All telemetry ingestion endpoints require a valid Clerk session (isSignedIn) on the server side
- Do not expose Clerk tokens or sessions to the client
- Validate user identity, and associate telemetry events with authenticated user IDs when available

Database rules:
- Use a ClickHouse table named telemetry_events with columns: event_time DateTime, user_id String, event_type String, metadata String
- Use parameterized inserts; avoid dynamic SQL string construction
- Implement retention/TTL policies via ClickHouse or deployment configuration

Validation rules:
- Validate incoming payloads (event_type, metadata) at API level with strict types
- Ensure metadata is JSON-serializable; store as a stringified JSON to avoid schema drift

Security rules:
- Never expose DB credentials or Clerk API keys to the client
- Sanitize inputs; reject unexpected event types and metadata shapes
- Enforce TLS for all network calls and apply rate limiting on telemetry endpoints

Testing rules:
- Unit tests for src/lib/db.ts and the telemetry helper with mocks
- Integration tests for src/routes/api/telemetry.ts validating payload handling and DB insertion
- End-to-end tests simulating Clerk sign-in and telemetry ingestion

Deployment rules:
- Deploy via adapter-node or your preferred Node adapter; provide environment variables in the hosting platform
- Ensure TLS, proper CORS settings, and server-side guards are active in production

Things Claude must not do:
- Do not call the database directly from the client
- Do not log or transmit PII to unsafe channels
- Do not bypass Clerk authentication checks or expose auth tokens

Recommended Project Structure

my-sveltekit-app/
  src/
    lib/
      clerk.ts        # Clerk initialization and helpers
      db.ts           # ClickHouse client wrapper
    routes/
      api/
        telemetry.ts  # server-side telemetry ingestion
        auth.ts       # Clerk-based auth utilities
    hooks.server.ts     # Clerk session loader for server hooks
  app.html
  routes/
    +layout.svelte
    +page.svelte
  tsconfig.json
  package.json
  .env.example

Core Engineering Principles

• Idempotent telemetry ingestion with deterministic behavior
• Least privilege and server-side protection for data flows
• Clear data contracts and strict input validation
• Observability: structured telemetry events and reliable logging

Code Construction Rules

• Use TypeScript with strict types; prefer interfaces for payloads
• Guard API routes with Clerk session validation on the server
• Use the ClickHouse Client with prepared/insertion API and typed payloads
• Store metadata as stringified JSON to avoid untyped fields
• Environment-based configuration; never hardcode credentials
• Keep client-side code free of direct database or secret access

Security and Production Rules

• Enforce Clerk authentication on telemetry endpoints
• Never send credentials or tokens to the client
• Use TLS, rate limiting, and proper CORS configuration
• Implement input validation and error handling that avoids leaking internals

Testing Checklist

• Unit tests for DB wrapper and telemetry helper
• Integration tests for server API telemetry.ts with valid/invalid payloads
• End-to-end tests for Clerk sign-in flow and telemetry ingestion
• Deployment smoke tests verifying environment configuration

Common Mistakes to Avoid

• Calling DB from the browser or client-side code
• Hard-coding credentials or API keys
• Lack of input validation leading to schema drift
• Disabling Clerk session checks on protected endpoints

FAQ

• Q: What is this CLAUDE.md Template for?
  A: It provides a ready-to-paste CLAUDE.md block for a SvelteKit + ClickHouse + Clerk Auth stack with telemetry via ClickHouse Client.
• Q: Which stack is covered?
  A: SvelteKit, ClickHouse, Clerk for authentication, and the ClickHouse Client for telemetry ingestion.
• Q: How is telemetry stored?
  A: Telemetry events are written to a ClickHouse table named telemetry_events on the server side.
• Q: How do I deploy?
  A: Use adapter-node with environment variables for ClickHouse and Clerk credentials and enable TLS.
• Q: How is security enforced?
  A: Clerk-backed server endpoints protect telemetry ingestion; secrets never reach the client.