SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise Blueprint - CLAUDE.md Template

Overview

This CLAUDE.md template page is designed for developers building enterprise applications with SvelteKit, PostgreSQL, WorkOS, and TypeORM Enterprise. It provides a copyable CLAUDE.md block that you can paste into Claude Code to bootstrap a production-ready blueprint and a stack-focused guide for implementation.

When to Use This CLAUDE.md Template

• You need a production-ready CLAUDE.md template for a SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise stack.
• You want a repeatable blueprint that enforces architecture, security, and deployment rules.
• You require a ready-to-paste instruction block plus a stack-specific project structure.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are Claude Code, an AI coding assistant specialized in delivering enterprise-grade blueprints for SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise.

Architecture Rules:
- Use a layered architecture: API (src/routes), service layer (src/services), data layer (src/entities), and persistence (src/db/migrations).
- Use TypeORM for PostgreSQL with a robust connection pool and transaction boundaries.
- Integrate WorkOS for authentication, SSO, and directory access.
- Do not mix client-side data fetches with server-side operations; keep SSR-safe patterns.

File Structure Rules:
- src/
  - routes/
  - lib/
  - db/
  - entities/
  - migrations/
  - services/
  - repositories/
  - config/
  - workos/
  - tests/
- config/.env.example for environment defaults.

Authentication Rules:
- Use WorkOS for SSO; store session identifiers in HttpOnly cookies; validate sessions on protected endpoints.
- Enforce role-based access control (RBAC) at the service layer.
- Never trust client-side tokens for authorization decisions.

Database Rules:
- PostgreSQL with TypeORM entities; migrations tracked in src/migrations.
- Use separate databases per environment; never share credentials across environments.
- Enforce referential integrity and proper indexing for query-heavy paths.

Validation Rules:
- Use zod for runtime input validation in API handlers.
- Fail closed on missing/invalid inputs with clear error messages.

Security Rules:
- Enforce CSRF protection for state-changing endpoints.
- Use TLS, secure cookies, and proper CORS configuration for trusted origins.
- Never log secrets or plaintext credentials.

Testing Rules:
- Unit tests for services and validators; integration tests for repositories and database interactions.
- End-to-end tests for authentication flows using Playwright or Cypress.

Deployment Rules:
- Local: Docker Compose; Staging/Prod: Kubernetes or serverless where supported.
- Run migrations as part of the deployment pipeline; verify migration success before promoting to prod.

Things Claude Must Not Do:
- Do not use Prisma, Mongoose, or Drizzle in this blueprint.
- Do not bypass WorkOS by mocking authentication tokens.
- Do not commit secrets or migrate data in code.
- Do not generate client-side code that leaks internal DB schemas.

Recommended Project Structure

src/
  routes/
  lib/
  db/
  entities/
  migrations/
  services/
  repositories/
  config/
  workos/
  tests/

Core Engineering Principles

• Explicit interfaces and typed contracts across layers.
• Single source of truth for business rules.
• Testable components with clear boundaries.
• Defensive programming and explicit error handling.
• 12-factor compliant configuration and secrets management.

Code Construction Rules

• Entities defined with TypeORM decorators; use migrations for schema changes.
• Repositories abstract data access; services orchestrate business logic.
• Validation with zod; return structured error payloads.
• Environment-driven configuration; no hard-coded values.
• Do not couple WorkOS keys with client code; fetch from server only.

Security and Production Rules

• Use HttpOnly secure cookies for sessions; enable CSRF protection.
• Enforce TLS in all environments; restrict CORS to trusted origins.
• Enable logging with redact for sensitive fields; rotate secrets regularly.
• Automate migrations; verify DB health during startup.

Testing Checklist

• Unit tests for services and validators; integration tests for repositories/migrations.
• End-to-end tests for authentication and protected routes.
• Migration sanity checks on CI/CD pipelines.

Common Mistakes to Avoid

• Using client-side sources to drive authorization decisions.
• Skipping migrations or mixing environments.
• Overexposing database schemas in API payloads.
• Ignoring WorkOS token validation or misconfiguring SSO.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Skill files for secure file upload implementations in production AI systems.

FAQ

What is included in this CLAUDE.md Template?

A copyable CLAUDE.md template block plus stack-specific guidelines for SvelteKit + PostgreSQL + WorkOS + TypeORM Enterprise.

Which stack does this template cover?

SvelteKit frontend, PostgreSQL database, WorkOS authentication, and TypeORM Enterprise as the ORM.

How do I integrate WorkOS into SvelteKit?

Install the WorkOS SDK, configure environment keys, and enforce SSO/session validation on protected routes.

How are migrations handled?

Use TypeORM migrations; run on deploy/startup; ensure migrations are applied before breaking changes.

Where should secrets live?

In environment variables or a secret manager; never commit secrets to code.