CLAUDE.md Template for SvelteKit + DynamoDB + AWS Cognito + Native Document Client Handler

Overview

A CLAUDE.md template page tailored for a SvelteKit application that uses DynamoDB via the native AWS SDK v3 Document Client and AWS Cognito for authentication. This template provides a copy-paste CLAUDE.md block and stack-specific guidance to keep the implementation consistent and secure across environments.

It targets developers building a server-rendered SvelteKit app with a serverless mindset, using the DynamoDB Document Client for JSON-friendly storage and Cognito for user pools and JWT-based authentication.

When to Use This CLAUDE.md Template

• You are implementing a SvelteKit app that requires persistent data in DynamoDB and user authentication with Cognito.
• You want a ready-to-paste CLAUDE.md template to guide Claude Code in implementing stack-specific patterns.
• You need explicit architecture, file-structure, and security rules to avoid drift in a team setting.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, an expert assistant for building a SvelteKit app that uses DynamoDB via the native AWS SDK v3 Document Client and AWS Cognito for authentication. Deliver precise, testable steps and concrete code blocks suitable for paste into a CLAUDE.md file.

Architecture rules:
1) Use SvelteKit with TypeScript for both client and server code.
2) Access DynamoDB only through the AWS SDK v3 Document Client; wrap calls in a dedicated data layer.
3) Use AWS Cognito for authentication; validate JWTs in server routes and protect sensitive endpoints.
4) Centralize business logic in src/lib (db, auth, validators) and keep route handlers thin.
5) Do not perform long-running tasks in routes; offload to background workers or queues where possible.
6) Keep environment-specific configuration out of code; read from environment variables and secret managers.

File structure rules:
- src/lib/db/dynamoClient.ts
- src/lib/auth/cognito.ts
- src/lib/validators.ts
- src/routes/api/items/+server.ts
- src/routes/api/users/+server.ts
- src/routes/+layout.server.ts
- src/hooks.server.ts
- .env.* (do not commit)

Authentication rules:
- Validate Cognito JWT in middleware for protected routes; verify iss, sub, aud, exp.
- Enforce token scopes/claims for access control (e.g., groups, roles).
- Do not reveal Cognito tokens to the client beyond necessary frontend access patterns.

Database rules:
- Tables: Users (PK: userId), Items (PK: itemId).
- Use DynamoDB Document Client for JSON objects; enable TTL where applicable.
- Do not store secrets in DynamoDB records; use kms/secret manager for keys.

Validation rules:
- Use a schema validator (e.g., zod) to validate all request bodies before DB access.
- Return 400 on validation errors with precise field-level messages.

Security rules:
- Do not embed AWS credentials in code; rely on IAM roles and environment-based credentials.
- Never log PII in plain text; redact sensitive fields in logs.
- Enforce least privilege on IAM roles used by the app.

Testing rules:
- Unit test the DynamoDB data layer with mocks for AWS SDK v3 clients.
- Integration test API routes with Cognito mocks for auth flows.
- End-to-end tests are optional but recommended; exercise login, data write/read paths.

Deployment rules:
- Set AWS region, Cognito user pool, and DynamoDB table names as environment variables.
- Ensure deployment platform (Vercel, Netlify, or AWS) preserves Secrets securely.
- Run unit and integration tests in CI before merging.

Things Claude must not do:
- Do not mutate DynamoDB tables directly without validation.
- Do not bypass Cognito authentication checks.
- Do not rely on static credentials or embed secrets in code.

Recommended Project Structure

my-sveltekit-app/
├─ src/
│  ├─ lib/
│  │  ├─ db/
│  │  │  └─ dynamoClient.ts
│  │  ├─ auth/
│  │  │  └─ cognito.ts
│  │  └─ validators.ts
│  ├─ routes/
│  │  ├─ +layout.server.ts
│  │  ├─ api/
│  │  │  ├─ items/
│  │  │  │  └─ +server.ts
│  │  │  └─ users/
│  │  │     └─ +server.ts
│  │  └─ +page.server.ts
│  └─ hooks.server.ts
├─ static/
├─ .env.local
├─ package.json

Core Engineering Principles

• Security by default: enforce authentication, authorization, and data validation at every boundary.
• Least privilege: IAM roles and policies strictly scoped to the app’s needs.
• Explicit data access: all DB operations go through a well-defined data layer.
• Observability: structured logging, request tracing, and error handling baked in.
• Immutability and idempotency: operations should be idempotent where possible.
• Environment parity: local development mirrors production as closely as possible.

Code Construction Rules

• Use TypeScript throughout the SvelteKit project; enable strict mode in tsconfig.
• All DynamoDB calls must use the Document Client interface from AWS SDK v3.
• Authentication checks occur in server routes or hooks; never trust client-side state for security.
• Validation is mandatory for all incoming payloads; fail fast with clear error messages.
• Separate concerns: UI logic in routes & UI components, business logic in src/lib, and data access in src/lib/db.
• Do not hard-code secrets; use environment variables or a secrets manager.

Security and Production Rules

• Validate Cognito JWTs on every protected endpoint; verify issuer and audience against your user pool.
• Store sensitive data in DynamoDB with encryption at rest and proper IAM policies.
• Use ephemeral credentials and rotate keys; avoid long-lived credentials in code.
• Audit and redact sensitive information in logs; enable monitoring and alerts for anomalous access patterns.
• Ensure environment-specific configs (staging, prod) are isolated and tested.

Testing Checklist

• Unit tests for data layer (dynamoClient.ts) with mocked AWS SDK v3 clients.
• Integration tests for Cognito auth flow (mock tokens, validate claims).
• API route tests for required inputs and error handling.
• End-to-end tests (optional) covering login, write, read, and delete flows with Cognito and DynamoDB.
• CI should run type checks, lint, and tests before merge.

Common Mistakes to Avoid

• Assuming client-side authentication is sufficient; always enforce server-side checks.
• Storing credentials in code or repo; always use environment-based config and secret managers.
• Mixing UI and business logic; keep a clean data layer abstraction for DB calls.
• Over-sharing Cognito user data in responses; sanitize and redact user attributes.

FAQ

• Q: How do I customize the Cognito User Pool in this template?
  A: Update COGNITO_USER_POOL_ID, COGNITO_REGION, and related claims handling in src/lib/auth/cognito.ts and in any server routes that validate tokens.
• Q: Which DynamoDB tables are required and how should they be structured?
• A: Users (PK: userId) and Items (PK: itemId). Include GSI or TTL as needed; access through the DynamoDB Document Client wrapper in src/lib/db/dynamoClient.ts.
• Q: How do I validate inputs?
• A: Use zod schemas in the server layer; validate all incoming payloads before invoking DB or business logic.
• Q: How should I deploy?
• A: Provide AWS region, Cognito pool IDs, and DynamoDB table names as environment variables; ensure secrets are not committed.